SPECIFICATION
第 9 章：エラーコードと適合性レベル
本章は CAP プロトコルの標準化エラーコード表、および実装が適合性レベルを宣言する方式を定義する。
9.1 エラーコード形式
エラーコードは E_ プレフィックスの大文字アンダースコアで命名する。エラーコード文字列自体が規範的である——本仕様の実装は MUST 本章定義に従い対応するエラーコード文字列を返却し、実装間の一貫した診断を可能にする。
エラー応答メッセージ構造：
ErrorBody {
required error_code : string
required message : string
optional details : map<string, string>
optional retry_after_ms : uint32
}
| フィールド | 説明 |
|---|---|
error_code | 本章定義の標準エラーコード |
message | 人間可読のエラー記述（言語固定なし、英語または日本語推奨） |
details | エラーの追加コンテキスト（違反した具体的フィールド等） |
retry_after_ms | クライアントリトライの推奨待機時間、暫定的エラーにのみ意義あり |
9.2 クレデンシャル関連エラーコード
Authorization_Descriptor および Trusted_Ticket の検証失敗シナリオに適用される。
| エラーコード | HTTP 等価 | 発動条件 | 適合性 |
|---|---|---|---|
E_DESCRIPTOR_NOT_FOUND | 404 | 参照される descriptor_id が端末ローカルに見つからない | 端末 MUST |
E_INVALID_STRUCTURE | 400 | クレデンシャル構造が §2.3 / §2.4 に適合しない | 端末/発行者 MUST |
E_INVALID_SIGNATURE | 401 | 署名検証失敗 | 端末 MUST |
E_VERIFICATION_KEY_INVALID | 401 | 署名 key_id に対応する Verification_Key が未登録または失効済み | 端末 MUST |
E_UNKNOWN_ISSUER | 401 | クレデンシャルの issuer_id が端末信頼リストに存在しない | 端末 MUST |
E_DESCRIPTOR_REVOKED | 403 | Authorization_Descriptor が失効済み | 端末 MUST |
E_TICKET_REVOKED | 403 | Trusted_Ticket が失効済み | 端末 MUST |
E_DESCRIPTOR_EXPIRED | 403 | クレデンシャルが not_after を経過 | 端末 MUST |
E_DESCRIPTOR_NOT_YET_VALID | 403 | 現在時刻が not_before より早い | 端末 MUST |
E_TICKET_MALFORMED | 400 | JWS 解析失敗または typ 不正 | 端末 MUST |
E_DUPLICATE_DESCRIPTOR_ID | 409 | 提出クレデンシャルが既保管クレデンシャル ID と衝突かつ内容不一致 | 端末 MUST |
E_VALIDITY_OUT_OF_RANGE | 400 | クレデンシャルの not_after - not_before が制限超過 | 端末/発行者 MUST |
E_REVOCATION_QUERY_TIMEOUT | 504 | オンライン失効照会タイムアウト | 端末 SHOULD |
9.3 認可範囲エラーコード
クレデンシャルが合法だが認可範囲がマッチしないシナリオに適用される。
| エラーコード | HTTP 等価 | 発動条件 |
|---|---|---|
E_SUBJECT_MISMATCH | 403 | クレデンシャル subject が要求者 fay_id と不一致 |
E_TERMINAL_MISMATCH | 403 | クレデンシャル terminal_id が現在端末と不一致 |
E_AUTHORIZATION_INSUFFICIENT | 403 | (resource, mode) にマッチする Grant が見つからない |
E_RATE_LIMIT_EXCEEDED | 429 | constraints の頻度制限を超過 |
E_OUT_OF_TIME_WINDOW | 403 | 現在時刻が constraints 時間ウィンドウ外 |
E_OUT_OF_GEO_FENCE | 403 | 端末位置が constraints 地理フェンス外 |
E_UNSUPPORTED_CONSTRAINT | 400 | クレデンシャルが未識別の constraint キーを含む |
9.4 リソースとセッションエラーコード
リソース占有、Session 状態関連のエラーに適用される。
| エラーコード | HTTP 等価 | 発動条件 |
|---|---|---|
E_RESOURCE_BUSY | 409 | リソースが要求モードで既に占有されている（読み書きロックマトリクス違反） |
E_RESOURCE_UNAVAILABLE | 503 | リソース現在利用不可（ハードウェア切断、ソフトウェア未起動等） |
E_RESOURCE_NOT_FOUND | 404 | resource_id が存在しない |
E_SESSION_NOT_FOUND | 404 | session_id が存在しない |
E_SESSION_TERMINATED | 410 | Session 終了済み、操作継続不可 |
E_SESSION_LIMIT_EXCEEDED | 429 | §5.8 定義の Session 数量制限を超過 |
E_OS_INTEGRATION_FAILED | 500 | OS アクセス制御下発失敗 |
9.5 ハンドオーバー関連エラーコード
第 6 章で定義されたハンドオーバーフローに適用される。
| エラーコード | HTTP 等価 | 発動条件 |
|---|---|---|
E_HANDOVER_INVALID_SOURCE | 400 | source_session_id が存在しないまたは状態がハンドオーバー不可 |
E_HANDOVER_INVALID_TARGET | 400 | target_credential 検証失敗 |
E_HANDOVER_REJECTED_BY_POLICY | 403 | ポリシー評価がハンドオーバー拒否 |
E_HANDOVER_FAILED_AT_RELEASE | 500 | ハンドオーバー過程中ソース Session 解放失敗 |
E_HANDOVER_FAILED_AT_ACQUIRE | 500 | ハンドオーバー過程中対象 Session 作成失敗 |
E_HANDOVER_TIMEOUT | 504 | ハンドオーバータイムアウト |
E_HANDOVER_IN_PROGRESS | 409 | リソースに進行中のハンドオーバーあり、新規要求拒否 |
E_HANDOVER_RETRY_LIMIT | 429 | リトライ回数が制限超過 |
9.6 プロトコルとシステムエラーコード
| エラーコード | HTTP 等価 | 発動条件 |
|---|---|---|
E_PROTOCOL_VERSION_UNSUPPORTED | 400 | メッセージ version フィールドが実装でサポートされない |
E_INVALID_MESSAGE | 400 | プロトコルメッセージ形式が §2.6 に適合しない |
E_INTERNAL_ERROR | 500 | 端末内部エラー（詳細を露出しない） |
E_NOT_IMPLEMENTED | 501 | 実装が当該オプション能力を提供していない |
E_STORAGE_FULL | 507 | 端末クレデンシャル保管満杯 |
9.7 エラーコード拡張
実装は MAY カスタムエラーコードを定義するが、MUST：
E_VENDOR_<vendor_name>_<code>命名形式を使用する（E_VENDOR_ACME_QUOTA_EXCEEDED等）- 本章定義の標準エラーコードと衝突しない
- 実装ドキュメントでセマンティクスを明示する
iFay_Runtime は未識別のカスタムエラーコード受領時、SHOULD E_INTERNAL_ERROR として処理する。
9.8 適合性レベル宣言
実装は MUST 以下の方式で満たす適合性レベルを宣言する。
9.8.1 適合性宣言構造
ConformanceClaim {
required protocol_version : string // "1.0.0" または "draft" 等
required levels : array<ConformanceLevel> (len 1..3)
optional optional_features : array<string>
optional vendor_extensions : array<string>
}
ConformanceLevel = enum["terminal", "issuer", "runtime"]
| フィールド | 説明 |
|---|---|
protocol_version | 実装が遵守する CAP プロトコルバージョン番号 |
levels | 実装が満たす適合性レベル（§0.5 を参照） |
optional_features | 実装がサポートするオプション能力（aggregated_heartbeat、ai_model_handover_policy 等） |
vendor_extensions | 実装がサポートするベンダー拡張能力 |
9.8.2 宣言公開チャネル
実装は SHOULD 以下のチャネルで ConformanceClaim を公開する：
- 製品ドキュメントで明示的に宣言
- 特定の照会インタフェースで返却（具体的インタフェースは実装で定義）
- SDK パッケージメタデータで宣言
9.8.3 適合性テスト
CAP プロトコルの適合性テストスイート（Conformance Test Suite）は補助資産としてプロジェクトが維持するが、本仕様の規範的範囲には含まれない。任意の実装は SHOULD 対応する適合性レベルのテストスイートに合格するが、MUST テストスイートを正しさの唯一の保証として依存しない。
9.9 エラーコード使用推奨
実装は SHOULD 以下のエラーコード使用原則に従う：
- 最も具体的なエラーコードを優先選択：例えば
E_TICKET_REVOKEDはE_TICKET_MALFORMEDより優先（両者が分析過程で出現可能性がある場合でも） - エラーコードを通じて内部詳細を露出しない：エラー message フィールドで鍵フィンガープリント、内部 ID 等の機微情報露出を回避
- details フィールドで診断補助を提供：例えば
details["field"] = "not_after"で具体的にどのフィールドが不適合かを示す - 暫定的エラーは retry_after_ms を使用：例えば
E_RESOURCE_BUSY、E_HANDOVER_IN_PROGRESS
9.10 エラーコードと schema.json の同期
schema/{version}/schema.json は MUST 完全なエラーコード列挙定義を含み、本章と一貫性を保つ。本章のエラーコードリスト更新時、schema.json は MUST 同期更新する。