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人類可讀的錯誤描述（語言不固定，建議英文或 zh-TW）
details錯誤的附加情境（如違反的具體欄位）
retry_after_ms客戶端重試的建議等待時間，僅對暫時性錯誤有意義

9.2 憑證相關錯誤碼

適用於 Authorization_Descriptor 和 Trusted_Ticket 的校驗失敗場景。

錯誤碼HTTP 等價觸發條件一致性
E_DESCRIPTOR_NOT_FOUND404引用的 descriptor_id 在終端本地未找到終端 MUST
E_INVALID_STRUCTURE400憑證結構不符合 §2.3 / §2.4終端/簽發方 MUST
E_INVALID_SIGNATURE401簽章校驗失敗終端 MUST
E_VERIFICATION_KEY_INVALID401簽章 key_id 對應的 Verification_Key 未註冊或已撤銷終端 MUST
E_UNKNOWN_ISSUER401憑證的 issuer_id 不在終端信任清單終端 MUST
E_DESCRIPTOR_REVOKED403Authorization_Descriptor 已被撤銷終端 MUST
E_TICKET_REVOKED403Trusted_Ticket 已被撤銷終端 MUST
E_DESCRIPTOR_EXPIRED403憑證已過 not_after終端 MUST
E_DESCRIPTOR_NOT_YET_VALID403目前時間早於 not_before終端 MUST
E_TICKET_MALFORMED400JWS 解析失敗或 typ 不正確終端 MUST
E_DUPLICATE_DESCRIPTOR_ID409提交的憑證與已儲存憑證 ID 衝突且內容不一致終端 MUST
E_VALIDITY_OUT_OF_RANGE400憑證的 not_after - not_before 超出限制終端/簽發方 MUST
E_REVOCATION_QUERY_TIMEOUT504線上撤銷查詢逾時終端 SHOULD

9.3 授權範圍錯誤碼

適用於憑證合法但授權範圍不比對的場景。

錯誤碼HTTP 等價觸發條件
E_SUBJECT_MISMATCH403憑證 subject 與請求方 fay_id 不比對
E_TERMINAL_MISMATCH403憑證 terminal_id 與目前終端不比對
E_AUTHORIZATION_INSUFFICIENT403找不到比對 (resource, mode) 的 Grant
E_RATE_LIMIT_EXCEEDED429超過 constraints 中的頻率限制
E_OUT_OF_TIME_WINDOW403目前時間不在 constraints 時間視窗內
E_OUT_OF_GEO_FENCE403終端位置不在 constraints 地理圍欄內
E_UNSUPPORTED_CONSTRAINT400憑證含有未識別的 constraint 鍵

9.4 資源與會話錯誤碼

適用於資源佔用、Session 狀態相關的錯誤。

錯誤碼HTTP 等價觸發條件
E_RESOURCE_BUSY409資源在請求模式下已被佔用（違反讀寫鎖矩陣）
E_RESOURCE_UNAVAILABLE503資源目前不可用（硬體斷開、軟體未執行等）
E_RESOURCE_NOT_FOUND404resource_id 不存在
E_SESSION_NOT_FOUND404session_id 不存在
E_SESSION_TERMINATED410Session 已終止，無法繼續操作
E_SESSION_LIMIT_EXCEEDED429超過 §5.8 定義的 Session 數量限制
E_OS_INTEGRATION_FAILED500OS 存取控制下發失敗

9.5 交接相關錯誤碼

適用於第 6 章定義的交接流程。

錯誤碼HTTP 等價觸發條件
E_HANDOVER_INVALID_SOURCE400source_session_id 不存在或狀態不允許交接
E_HANDOVER_INVALID_TARGET400target_credential 校驗失敗
E_HANDOVER_REJECTED_BY_POLICY403策略評估拒絕交接
E_HANDOVER_FAILED_AT_RELEASE500交接過程中源 Session 釋放失敗
E_HANDOVER_FAILED_AT_ACQUIRE500交接過程中目標 Session 建立失敗
E_HANDOVER_TIMEOUT504交接逾時
E_HANDOVER_IN_PROGRESS409資源已有交接進行中，新請求被拒絕
E_HANDOVER_RETRY_LIMIT429重試次數超過限制

9.6 協議與系統錯誤碼

錯誤碼HTTP 等價觸發條件
E_PROTOCOL_VERSION_UNSUPPORTED400訊息 version 欄位不被實作支援
E_INVALID_MESSAGE400協議訊息格式不符合 §2.6
E_INTERNAL_ERROR500終端內部錯誤（不暴露細節）
E_NOT_IMPLEMENTED501實作未提供該可選能力
E_STORAGE_FULL507終端憑證儲存已滿

9.7 錯誤碼擴充

實作 MAY 定義自訂錯誤碼，但 MUST：

  1. 使用 E_VENDOR_<vendor_name>_<code> 命名格式（如 E_VENDOR_ACME_QUOTA_EXCEEDED）
  2. 不與本章定義的標準錯誤碼衝突
  3. 在實作文件中明確語意

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：

  1. 在產品文件中明確宣告
  2. 透過特定查詢介面返回（具體介面由實作定義）
  3. 在 SDK 套件元資料中宣告

9.8.3 一致性測試

CAP 協議的一致性測試套件（Conformance Test Suite）作為輔助資產由專案維護，但不在本規範的規範性範圍內。任何實作 SHOULD 通過對應一致性等級的測試套件，但 MUST 不依賴測試套件作為正確性的唯一保證。

9.9 錯誤碼使用建議

實作 SHOULD 遵循以下錯誤碼使用原則：

  1. 優先選擇最具體的錯誤碼：例如 E_TICKET_REVOKED 優於 E_TICKET_MALFORMED（即使兩者都可能在分析過程中出現）
  2. 不透過錯誤碼暴露內部細節：錯誤 message 欄位中避免暴露金鑰指紋、內部 ID 等敏感資訊
  3. details 欄位提供診斷輔助：例如 details["field"] = "not_after" 表明具體哪個欄位不合規
  4. 暫時性錯誤使用 retry_after_ms：例如 E_RESOURCE_BUSY、E_HANDOVER_IN_PROGRESS

9.10 錯誤碼與 schema.json 的同步

schema/{version}/schema.json MUST 包含完整的錯誤碼列舉定義，與本章保持一致。當本章錯誤碼清單更新時，schema.json MUST 同步更新。