錯誤處理

所有錯誤都是同一種結構。

出錯時 HTTP 狀態碼非 2xx，回應內容裡只有一個 error 物件：

json

{
  "error": {
    "message": "Insufficient credits: this request needs 60 credits. Top up and try again.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_credits"
  }
}

欄位

欄位	說明
message	給人看的英文說明。不要用它做程式分支——文案會調整
type	錯誤大類，見下表
code	具體原因。程式分支請判斷這個欄位
param	出問題的參數名，無法定位到具體參數時為 null

常見錯誤

HTTP	code	含義與處理
401	missing_api_key	沒帶 Authorization 標頭，或格式不是 Bearer sk-xxx
401	invalid_api_key	金鑰無效、已停用或已刪除。三種情況合併同一句文案，不區分
400	invalid_request	參數有問題，看 message。例如 prompt 為空、圖生影片沒給圖
402	insufficient_credits	算力不足。加購後重試，重試前建議先查 /v1/credits
429	rate_limit_exceeded	呼叫過於頻繁，退避後重試
429	concurrency_limit_reached	並行或每日額度受限，稍後重試
404	not_found	任務不存在，或不屬於目前金鑰所屬帳號
502	generation_failed	同步出圖時全部出圖失敗，算力已自動退還
504	generation_timeout	同步出圖等待逾時。任務仍在跑、算力不退，用 message 裡的任務 id 去 /v1/tasks/{id} 取結果
500	internal_error	伺服器異常。可重試，若持續出現請聯絡我們

非同步送出成功後如果算圖失敗，不會走這裡的錯誤結構——那時介面是 200，任務物件的 status 為 failed，原因在 error 欄位裡。只有同步出圖會把失敗直接拋成 502。