--- title: Gateway 錯誤代碼 description: Gateway 的 /v1 端點會回傳的每一個錯誤代碼，附上 HTTP 狀態碼、重試有沒有用，以及怎麼修。 url: https://agentlab.cresclab.com/docs/zh-tw/gateway/errors language: zh-Hant updated: 2026-10-28 --- # 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 狀態頁](https://agentlab.cresclab.com/status)不用登入，會從你的瀏覽器檢查我們託管的 Gateway 是否就緒，並說明每種結果該怎麼做。 ## 代碼一覽 | 代碼 | 狀態碼 | 重試 | 怎麼辦 | | ----------------------------------- | -------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `application_key_required` | 401 | 不要 | 用 `Authorization: Bearer ` 送出金鑰（或用 `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 頁](https://agentlab.cresclab.com/gateway#demo)申請開通。 | | `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 參考](https://agentlab.cresclab.com/docs/zh-tw/gateway/api.md#chat-completions)。 | | `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 個字元。見[標籤](https://agentlab.cresclab.com/docs/zh-tw/gateway/usage.md#tags)。 | | `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 可能送出、但這裡沒有列的代碼，會讓建置失敗。