API 文件 · 可靠性

錯誤碼

統一的錯誤格式與完整錯誤碼。

所有錯誤都使用統一格式（請見右側範例）。下表列出 API 可能回傳的 error.code 及其 HTTP 狀態碼，同一個狀態碼可能對應多個錯誤碼：

HTTP	code	情境	可重試	建議
400	`invalid_request`	JSON 格式錯誤、Content-Type 不是 application/json，或缺少 / 超長的 Idempotency-Key；請求內容超過 1 MB 時為 413	否	修正請求後重新送出
401	`invalid_api_key`	Key 不存在、已撤銷、已過期或已停用	否	在主控台檢查 Key 狀態
401	`unauthenticated`	主控台工作階段未登入或已過期	否	重新登入
402	`quota_exceeded`	帳號可用額度不足；凍結上限超過 max_budget（param 為 max_budget）；素材儲存空間已滿	否	補充額度、調整 max_budget 或清理素材後重試
402	`key_limit_exceeded`	Key 的累計或每日限額不足	否	調整 Key 限額後重試
403	`permission_denied`	Key 缺少 scope、模型不在 Key 白名單中，或帳號未開通該模型	否	在主控台為 Key 新增權限，或聯絡營運團隊開通模型
403	`csrf_failed`	主控台請求缺少 CSRF 權杖或權杖已失效	否	重新整理頁面後重試
403	`account_suspended`	帳號已遭停用	否	聯絡營運團隊
404	`not_found`	資源不存在，或不屬於你	否	確認 ID 是否正確
404	`not_available`	僅海外站提供的功能在本站不可用	否	改用對應站點
403	`terms_required`	尚未同意最新的儲值須知	否	閱讀並同意儲值須知後重試
409	`idempotency_conflict`	冪等鍵相同，但請求內容不同	否	新請求請使用新的冪等鍵
409	`conflict`	資源狀態衝突	否	重新查詢最新狀態後再操作
409	`group_not_empty`	群組內仍有素材	否	先移出或刪除群組內的素材
422	`invalid_parameter`	參數不合法或組合不受支援（不會默默捨棄）	否	對照能力表修正參數
422	`asset_not_ready`	素材仍在處理中	是	等待狀態變為 available 後重試
422	`authorization_required`	真人素材缺少有效授權	否	完成真人授權後重試
429	`rate_limited`	超出 Key 的 RPM，或帳號 / Key 的並行上限	是	依 Retry-After 退避後重試
500	`internal_error`	平台內部錯誤	是	以同一個冪等鍵重試

retryable 為 true 時可退避後重試；重試建立任務時必須帶同一個 Idempotency-Key。

受理後才發生的失敗（例如暫時沒有可用線路）不會以 API 錯誤回傳，而是反映在任務的 error.code 中，請見任務失敗碼。

錯誤回應

HTTP/1.1 422 Unprocessable Entity
X-Request-Id: req_xxx

{
  "error": {
    "code": "asset_not_ready",
    "message": "素材 asset_xxx 仍在處理中，請在狀態變為 available 後重試",
    "param": "inputs[0].asset_id",
    "retryable": true,
    "request_id": "req_xxx"
  }
}