處理 API 錯誤

請根據 HTTP 狀態碼和 code 來處理錯誤。message 欄位是為人類閱讀而編寫的，可能會隨時變更，恕不另行通知。

Chat Completions 和 Responses 使用 OpenAI 風格的 error 物件。Anthropic Messages 和 Gemini 則保留其各自的錯誤格式，因此請勿對所有 TokenLab API 使用同一種解析器。

{
  "error": {
    "message": "Human-readable description",
    "type": "error_type",
    "code": "error_code",
    "param": "parameter_name",
    "retryable": true,
    "retry_after": 30
  }
}

在 TokenLab 建立的 OpenAI 相容錯誤中，僅 message 和 type 是必定存在的。其他欄位僅在相關時才會出現。

狀態碼

狀態	含義	建議操作
`400`	欄位、模型 ID 或輸入無效	修改請求；請勿在未修改的情況下重複發送
`401`	API key 遺失、無效、過期或已撤銷	更換 API key
`402`	餘額不足或達到 API-key 限制	儲值、提高限制或減少請求量
`403`	此 key 無權使用該資源或模型	更改 key 的權限或更換模型
`404`	資源不存在或已無法存取	檢查 ID 以及建立該資源的 API key
`413`	請求或上傳的檔案過大	縮減輸入內容或檔案，使其符合模型或端點公布的限制
`429`	已達請求限制	等待 `Retry-After` 指定的時間
`500`–`504`	服務無法使用或網路故障	僅在 `retryable` 為 `true` 時重試，並遵守 `retry_after` 和次數限制

常見錯誤代碼

代碼	含義	應採取的變更
`invalid_api_key`	API 金鑰缺失、無效、已停用或撤銷	檢查 Authorization 標頭與 key 值
`expired_api_key`	API 金鑰已過期	建立或選擇一個有效的 key
`insufficient_balance`	帳戶餘額不足以支付請求	儲值、減少請求量或選擇價格較低的模型
`quota_exceeded`	API key 已達其自身限制	提高該 key 的限制或使用其他已授權的 key
`model_not_allowed`	此 key 無權使用請求的模型	更新 key 的模型列表或選擇允許的模型
`model_not_found`	模型 ID 未知或不可用	查閱 `/v1/models` 並使用當前的模型 ID
`context_length_exceeded`	輸入長度超過模型限制	刪除歷史記錄或選擇具有更大上下文視窗的模型
`rate_limit_exceeded`	在當前時間視窗內請求過多	等待 `Retry-After` 指定的時間
`payload_too_large`	請求主體或檔案超過端點限制	減少或壓縮輸入內容
`all_channels_failed`	所選模型無法處理這次請求	僅在 `retryable` 為 `true` 時重試，並遵守 `retry_after` 和次數限制
`timeout_error`	請求未在時限內完成	僅在操作可安全重複時進行重試

503 all_channels_failed 或 503 delivery_tier_unavailable 不一定是暫時性故障。如果所選 Delivery 層級沒有支援目前操作的供應，retryable 為 false，且不回傳 retry_after，請勿原樣重試。更換模型前，透過 GET /v1/models 檢查對應操作和 Delivery 的可用性。名稱相近不代表可用；未經驗證的替代模型不會列出。

部分 OpenAI 相容錯誤包含選用的 did_you_mean、suggestions、alternatives、hint、retryable 或 retry_after 欄位。請參閱代理可處理的錯誤。

如果請求走的是 Official 線路，且上游服務拒絕了請求本身（例如不接受的輸入或內容政策判定），錯誤中還會帶有 upstream：其中 message 是上游給出的原文，已知時還有 code 和 source（上游服務名稱）。Anthropic Messages 和 Gemini 的錯誤會在各自的 error 物件中帶有同樣的欄位。請繼續依 code 和 type 分支處理；upstream.code 由上游服務定義，可能變動。

重試決策

錯誤	是否重複相同請求？
`400`, `401`, `402`, `403`, `404`, `413`	否。請更改請求、憑證、餘額、權限或輸入內容。
`429`	是，請在伺服器提供的延遲時間後重試。
`500`–`504`	僅在 `retryable` 為 `true` 時重試，並遵守 `retry_after` 和次數限制
連線在收到任何回應前中斷	有時。對於建立操作，請先檢查任務或副作用是否已存在。
串流在輸出到達後中斷	請勿視為完整回應。重複請求可能會產生不同的輸出或導致二次扣款。

對於圖像、影片、音樂、3D 和 Worlds 的建立任務，請在收到任務 ID 後立即儲存。如果建立請求逾時，請在發送另一個建立請求前檢查任務記錄。

保留 Request ID

回應標頭包含用於追蹤的 Request ID。請將其與端點、模型、時間以及您自己的使用者或工作 ID 一併儲存。對於非同步工作，若存在 task_id 和 billing_transaction_id，也請一併儲存。

聯繫支援團隊時，請提供這些 ID 以及去識別化後的範例。切勿傳送 API keys、管理權杖 (management tokens)、私人媒體、簽名 URL 或完整的私人提示詞 (prompts)。

從請求詳情到調查與人工支援

處理 API 錯誤

狀態碼Copy Anchor Link

常見錯誤代碼Copy Anchor Link

重試決策Copy Anchor Link

保留 Request IDCopy Anchor Link

本頁內容

狀態碼

常見錯誤代碼

重試決策

保留 Request ID