Gateway 錯誤代碼
Gateway 的 /v1 端點會回傳的每一個錯誤代碼，附上 HTTP 狀態碼、重試有沒有用，以及怎麼修。
代碼在哪裡#
每個端點都用自己協定的錯誤格式回答，官方 SDK 才讀得懂：
/v1/chat/completions和/v1/responses：{"error": {"message", "type", "param", "code"}}。代碼在error.code。/v1/messages和/v1/messages/count_tokens：{"type": "error", "error": {"type", "message"}}。代碼就是 message；429 例外，它帶的是看得懂的訊息，代碼放在error.code。/v1/models用發出請求的用戶端的格式回答：請求帶有anthropic-version或x-api-key時用 Anthropic 格式，否則用 OpenAI 格式。
供應商自己寫的拒絕（關於你請求內容的 400、413 或 422），會照供應商的原文轉回給你，沒有 Gateway 代碼。
重試標頭：Retry-After 表示要等幾秒。X-Should-Retry: false 告訴 OpenAI 和 Anthropic SDK 完全不要重試。
是 Gateway 的問題嗎？#
收到 5xx 錯誤，或完全沒有回應？Gateway 狀態頁不用登入，會從你的瀏覽器檢查我們託管的 Gateway 是否就緒，並說明每種結果該怎麼做。
代碼一覽#
| 代碼 | 狀態碼 | 重試 | 怎麼辦 |
|---|---|---|---|
application_key_required | 401 | 不要 | 用 Authorization: Bearer <key> 送出金鑰（或用 x-api-key，/v1/chat/completions 除外）。 |
application_key_not_accepted | 401 | 不要 | 金鑰已撤銷、已到期、打錯，或是從允許清單以外的位址使用。到金鑰清單檢查，或建立一把新的。 |
gateway_key_attempts_exceeded | 429 | 等 Retry-After 後 | 你的位址送出太多不被接受的金鑰。先修正工具送出的金鑰，再等一下。 |
gateway_key_model_not_allowed | 403 | 不要 | 金鑰的模型允許清單不含這個模型。改用清單裡的模型或 auto，或修改金鑰的允許清單。 |
server_application_required | 403 | 不要 | 請求來自瀏覽器（有 Origin 標頭），或帶了不該有的 query string。請從伺服器、CLI 或腳本呼叫 Gateway。 |
inference_not_admitted | 403 | 不要 | 這個工作區目前不能使用 Gateway，或選到的模型不能使用。請在 AI Gateway 頁申請開通。 |
model_not_enabled | 403 | 不要 | 工作區的模型設定排除了這個模型。改用其他模型或 auto，或請擁有者或管理員開放它。 |
model_not_found | 404, 400 | 不要 | 模型不存在，或這個端點沒有允許的模型能處理這個請求。改用 GET /v1/models 裡的名稱或 auto。 |
video_not_found | 404 | 不要 | 這把 API key 沒有建立過這個 id 的影片。影片只能用建立它的那把 key 讀取。 |
invalid_model | 400 | 不要 | agentlab/… 的名稱不是模型。改用 auto 或 GET /v1/models 裡的名稱。 |
invalid_provider | 400 | 不要 | provider.only 裡有不是供應商的名稱、排除了你指定的模型，或列出的供應商沒有任何模型能處理這個請求（error.param 為 provider.only）。修正清單；訊息會列出可用的供應商。 |
unsupported_parameter | 400 | 不要 | 請求帶了 Gateway 不接受的 OpenAI 欄位（error.param 是那個欄位）。移除該欄位。 |
prompt_reference_invalid | 400 | 不要 | 在 /v1/prompts/{prompt}/completions 以提示詞的 id 或 slug 指名，可在後面加 @<版本>。 |
prompt_not_found | 404 | 不要 | 金鑰所屬的工作區沒有這個名稱的提示詞或版本。請到該工作區的「提示詞」分頁確認。 |
prompt_variables_mismatch | 400 | 不要 | variables 必須剛好是提示詞的變數。訊息會列出缺少的變數與提示詞沒用到的變數。 |
prompt_variables_invalid | 400 | 不要 | variables 必須是值皆為字串的物件。 |
prompt_messages_not_accepted | 400 | 不要 | 呼叫提示詞時送 variables，不送 messages：訊息由提示詞提供。 |
prompt_too_large | 400 | 不要 | 填入這些變數後的提示詞超過單一請求的大小上限。請縮短變數值。 |
invalid_inference_request | 400 | 不要 | Chat Completions 的 body 用了 Gateway 不接受的欄位或值。見 API 參考。 |
invalid_request | 400 | 不要 | Responses 的 body 要求了儲存的狀態（previous_response_id、conversation、prompt）或被拒絕的工具。param 會寫出是哪個欄位。 |
request_key_invalid | 400 | 不要 | Idempotency-Key 最多只能送一次，長度要在 8 到 128 個字元之間。 |
request_key_already_used | 409 | 不要 | 這個 Idempotency-Key 已經用過了。新的請求請送新的 key。 |
routing_header_invalid | 400 | 不要 | X-AgentLab-Routing 必須剛好是 auto，而且只送一次。 |
invalid_metadata | 400 | 不要 | X-AgentLab-Metadata 或內文 metadata 裡的標籤無法記錄；訊息會說違反哪一條。送一個最多 16 個字串值的 JSON 物件，鍵為 1 到 64 個英數字、_、. 或 -，值為 1 到 512 個字元。見標籤。 |
json_required | 415 | 不要 | 送出 Content-Type: application/json。 |
request_too_large | 413 | 不要 | body 超過端點接受的大小：Chat Completions、語音和圖片生成是 1 MiB，Messages 和 Responses 是 32 MiB，語音轉文字是 26 MiB（音檔最多 25 MiB），圖片編輯和影片是 64 MiB。 |
request_body_unreadable | 400 | 要 | 請求的 body 在宣告的長度之前就中斷了，或沒有及時送達。重新送出請求。 |
gateway_guardrail_blocked | 400 | 不要 | 工作區的防護規則找到會擋下的內容（卡號、API 金鑰、清單上的字詞……），訊息會寫出是哪一項檢查。移除那段內容，或請工作區管理員在 AI Gateway › 開始使用調整防護規則。 |
inference_allowance_exceeded | 429 | 不要 | 某個每月額度、部門上限或滾動時段已經用完，訊息會寫出是哪一個。調高它，或等額度重設。Free 方案時也可能是方案內含的請求數或模型花費（gateway_plan_requests、gateway_plan_spend）；儲值方案則是餘額不足（gateway_balance）。在 AI Gateway › 方案 儲值，同一把金鑰立即可用。 |
gateway_rate_limited | 429 | 等 Retry-After 後 | 這把金鑰或工作區每分鐘送出的請求數或 token 數超過了速率上限，或同時處理中的音訊、圖片、影片請求已達 Gateway 的上限。等一下，或調高上限。 |
provider_rate_limited | 429 | 等 Retry-After 後 | 模型供應商忙碌中。SDK 會自己等待並重試。 |
count_tokens_concurrency_exceeded | 429 | 等 Retry-After 後 | 同時送出太多計算 token 的請求。一秒後再試。 |
provider_overloaded | 529 | 要 | 模型供應商超載。稍後再試，或改用 auto 或其他模型。 |
inference_failed | 502 | 要，一次 | 供應商沒能回答。如果一直失敗，到 AI Gateway › 用量打開這個請求查看。 |
settlement_pending | 503 | 不要 | 模型已經回答，但用量還沒能記錄，所以先不交出回答。請不要重送：它會自己結算。 |
inference_unavailable | 503 | 要 | Gateway 連不到做決定所需的服務。稍後再試。 |
gateway_unavailable | 503 | 要 | Gateway 伺服器正在啟動或重新載入設定。稍後再試。 |
gateway_not_configured | 503 | 不要 | 這台伺服器沒有設定 Gateway。如果是自行架設的 Gateway，請檢查它的部署設定。 |
transport_deadline_unavailable | 503 | 要 | 伺服器無法設定連線的時間限制。請重試。 |
每次建置都會拿這張表和 Gateway 的程式碼比對：Gateway 可能送出、但這裡沒有列的代碼，會讓建置失敗。