錯誤

Management API、Content Delivery API 及 Customer API 回傳的錯誤格式均一致。每個錯誤代碼在所有 API 中皆對應相同的 HTTP 狀態碼，因此您只需編寫一個錯誤處理器，即可應用於所有 API。

{
  "error": {
    "code": "SLUG_TAKEN",
    "message": "Another post already uses this slug.",
    "details": { "slug": "how-we-feed-our-starter" }
  }
}

成功的回應絕不會包含 error 欄位，且 API 不會將成功回應包裹在 ok 旗標中。

錯誤代碼對應的 HTTP 狀態碼

每個錯誤代碼皆對應一個狀態碼。未來新增的代碼亦遵循相同規則，因此您可以根據狀態碼來處理尚未遇過的錯誤代碼。

API 參考文件中的每項操作皆列出了其可能回傳的錯誤代碼及其含義。OpenAPI 文件中亦包含相同的列表，標記為 x-kanorio-errors。

驗證錯誤

VALIDATION 錯誤會在 details.issues 中列出所有驗證失敗的欄位。path 欄位使用點號（.）來表示巢狀結構。

{
  "error": {
    "code": "VALIDATION",
    "message": "Input does not match the capability schema.",
    "details": {
      "issues": [
        { "path": "title", "message": "Required", "code": "invalid_type" }
      ]
    }
  }
}

Content Delivery API 的表單提交若有無效回答，會以相同方式回報，並將問題 ID 作為 path。

重試機制

• 針對 429、502 及 503 錯誤，請使用退避演算法（backoff）進行重試。若回應中包含 Retry-After 標頭或 details.retryAfter 欄位，請至少等待該秒數後再重試。
• 請勿直接重試其他 4xx 錯誤，應先修正請求內容。
• 若寫入操作出現 409 CONFLICT，代表資源在您讀取後已被他人修改。請重新讀取資源、合併變更，並使用新的時間戳記再次發送寫入請求。
• 請使用 冪等性鍵值 確保建立請求可安全重試。

權限錯誤

403 回應會在 details 中說明缺失的權限，例如權杖缺乏的 requiredScope，或是當服務帳戶呼叫帳戶層級操作時顯示 reason: "principal_not_allowed"。遇到此類錯誤時，請引導使用者進行修正，而非進行重試。

請求識別碼

Content Delivery API 及 Customer API 的回應皆包含 X-Request-Id 標頭。若需聯絡支援團隊查詢特定請求，請提供此識別碼。

錯誤代碼

下表列出了目前各 API 可能回傳的所有錯誤代碼，內容由 OpenAPI 文件自動產生。

Management API codes

Content Delivery API codes

Customer API codes