Source: https://ailoot.ai/docs/zh-hant-tw/errors/ Canonical: https://ailoot.ai/docs/zh-hant-tw/errors/ Language: zh-hant-tw [說明](https://ailoot.ai/docs/zh-hant-tw/) # 錯誤與限制 [Markdown](https://ailoot.ai/docs/zh-hant-tw/errors/index.md) 回應代碼、含義與處理方式。所有錯誤皆以 JSON 傳回，並附帶 Request ID。 ## [](https://ailoot.ai/docs/zh-hant-tw/errors/#format)錯誤格式 錯誤會採用您呼叫的 API 格式：物件`error`用於 OpenAI， `{"type": "error", "error": {...}}`用於 Anthropic，以及`error` ，其欄位包含`status`與`details` ，用於 Gemini。因此 SDK 會將它們辨識為一般 API 錯誤。 - `error.code`與`error.reason` —下方表格中的錯誤類別，兩者相同。`error.type` —該格式的標準值 (例如`invalid_request_error`或`server_error`). - `error.request_id` (Anthropic 使用`request_id`頂層欄位)，標頭`X-Request-ID`及訊息文字末尾，都會提供請求識別碼。 - Gemini 的錯誤類別位於`error.details`：`ErrorInfo.reason` —相同代碼的大寫形式 (例如`MODEL_OVERLOADED`), `domain` — `ailoot.ai`; 請求識別碼位於`RequestInfo.requestId`。 - 在 Gemini 格式中，不能自動重試的 5xx 錯誤，以及`result_pending_check` ，會以 409 狀態及`status` `ABORTED`傳回，讓 Gemini SDK與CLI 不會自行重試。錯誤類別位於`ErrorInfo.reason` (例如`MODEL_TIMEOUT`或`RESULT_PENDING_CHECK`). - OpenAI 格式的回應還包含頂層欄位`code`與`message` —供舊版用戶端使用。 ```json { "code": "API_KEY_REQUIRED", "error": { "code": "invalid_api_key", "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer \". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.", "param": null, "reason": "invalid_api_key", "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6", "type": "invalid_request_error" }, "message": "No API key was sent with the request. Nothing was charged. …" } ``` ```json { "type": "error", "error": { "type": "authentication_error", "code": "invalid_api_key", "reason": "invalid_api_key", "message": "… Nothing was charged. … Request ID: 94ed3e31-4373-41ce-bf8a-0d1ed3f7235e." }, "request_id": "94ed3e31-4373-41ce-bf8a-0d1ed3f7235e" } ``` ```json { "error": { "code": 401, "status": "UNAUTHENTICATED", "message": "The API key is not valid. Nothing was charged. … Request ID: e7aa743b-9d0d-4064-b206-2562609f545b.", "details": [ { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "INVALID_API_KEY", "domain": "ailoot.ai", "metadata": { "code": "invalid_api_key", "reason": "invalid_api_key", "request_id": "e7aa743b-9d0d-4064-b206-2562609f545b" } }, { "@type": "type.googleapis.com/google.rpc.RequestInfo", "requestId": "e7aa743b-9d0d-4064-b206-2562609f545b" } ] } } ``` “Nothing was charged” 表示款項未扣除。若收到 X-Should-Retry: false，請勿自動重試，應先在歷史紀錄中檢查 Request ID。 ## [](https://ailoot.ai/docs/zh-hant-tw/errors/#codes)錯誤代碼 | HTTP | 類別 (reason) | 發生的問題 | 處理方式 | | --- | --- | --- | --- | | 400 | `invalid_request` | 請求不正確：主體或參數有誤；模型不支援請求中的欄位、附件或工具；金鑰放在位址中 | 請依錯誤文字修正請求：移除不支援的欄位、附件或工具，並在標頭中傳入金鑰。因不支援欄位、附件或工具而拒絕的請求，會在保留金額前遭到拒絕，不會扣款 | | 400 | `context_length_exceeded` | 請求長度超過模型的上下文上限 | 縮短歷史訊息，或選用上下文更大的模型 | | 400 | `content_policy_violation` | 模型規則拒絕了此請求 | 重新表達請求內容 | | 401 | `invalid_api_key` | 未提供金鑰，或金鑰不正確 | 確認金鑰已完整傳入 | | 401 | `api_key_disabled` | 金鑰已停用 | 啟用金鑰，或建立新的金鑰 | | 402 | `insufficient_balance`，`insufficient_quota` | 可用餘額連最低保留金額都不足 (`insufficient_quota` —同一情況，以 OpenAI SDK 慣用的格式表示) | 儲值，或降低 max\_tokens | | 402 | `api_key_quota_exhausted` | 金鑰的總支出上限已用盡 | 在控制台提高金鑰上限 | | 402 | `payment_disputed` | 帳戶因付款爭議而有欠款 | 清償前會暫停新的請求，請聯絡客服 | | 403 | `api_key_expired` | 金鑰已過期 | 建立新的金鑰 | | 403 | `account_inactive` | 您的帳戶已停用 | 聯絡客服 | | 403 | `permission_denied` | 此金鑰無權執行此請求 (例如因 IP 限制) | 檢查金鑰限制 | | 404 | `model_not_found` | 找不到此模型 | 與/v1/models 中的 ID 核對 | | 404 | `unsupported_endpoint` | 模型不支援此格式 | 選擇其他格式或模型 | | 404 | `not_found` | 找不到此路徑或物件 (例如任務) | 檢查位址與識別碼 | | 409 | `duplicate_request` | 使用相同冪等金鑰的操作已被接受，也可能已完成 | 檢查第一個操作的結果，請勿傳送新的操作 | | 409 | `not_ready`，`video_not_ready` | 影片或其他任務尚未完成 | 稍後查詢狀態 | | 409, 503 | `result_pending_check` | 正在確認請求結果。影片任務會在狀態回應中以此旗標表示：`result_pending_check: true` ，而任務本身仍為`in_progress` | 請勿重新傳送請求，狀態會出現在歷史紀錄中 (GET https://ailoot.ai/api/v1/usage)。也不要重新建立影片任務，請稍後透過 GET /v1/videos/{id} 檢查 | | 410 | `model_retired` | 模型已停止提供服務 | 從 GET /v1/models 選擇新版本 | | 413 | `request_too_large` | 請求主體過大 | 縮小檔案，或減少歷史訊息 | | 429 | `rate_limit_exceeded`，`gateway_concurrency_limit`，`gateway_queue_full` | 您的帳戶請求數或同時進行的請求數過多 | 請稍候 (依此標頭：`Retry-After`，通常為 10 秒)，再重試 | | 429 | `usage_limit_reached` | 金鑰在時間視窗內的支出額度已用盡 (5 小時、1 天或 7 天) | 等待時間視窗更新，或提高金鑰上限 | | 500 | `internal_error` | Ailoot 錯誤 | 請提供 Request ID 聯絡客服 | | 502 | `invalid_model_response`，`empty_response`，`incomplete_response` | 模型傳回不正確、空白或不完整的回應 | 請在帳戶介面的歷史紀錄中查找 Request ID。若已有結果或扣款紀錄，重試會建立第二筆付費請求。沒有紀錄不代表請求未送出或未執行：請勿重送傳送狀態不明的請求；請附上 Request ID 聯絡支援。 | | 502 | `result_not_delivered` | 因 Ailoot 的問題而未能交付結果，保留金額或已扣款金額已退回 | 可以重新傳送請求 | | 503 | `model_overloaded` | 模型暫時過載 | 若 X-Should-Retry: true，請等待 Retry-After 指定的秒數後再次嘗試；若為 false，請先在歷史紀錄中檢查 Request ID | | 503 | `model_unavailable` | 模型暫時無法使用 | 選擇其他模型。若 X-Should-Retry: true，請等待 Retry-After 指定的秒數後重試；若為 false，請先在歷史紀錄中檢查 Request ID | | 503 | `service_unavailable` | Ailoot 端暫時發生故障 | 若 X-Should-Retry: true，請等待 Retry-After 指定的秒數後再次嘗試；若為 false，請先在歷史紀錄中檢查 Request ID | | 503 | `charge_not_confirmed` | 回應未交付：無法確認扣款，保留金額已退回，款項未扣除 | 若 X-Should-Retry: true，請等待 Retry-After 指定的秒數後再次嘗試；若為 false，請先在歷史紀錄中檢查 Request ID | | 504 | `model_timeout` | 模型未在期限內回應，但結果仍可能出現 | 在歷史紀錄中檢查 Request ID 前，請勿重新傳送請求 | 模型回應與結果檢查相關的代碼 (502、503與504)，現在會指明模型或請求：`model_unavailable`，`model_timeout`，`invalid_model_response`，`incomplete_response`，`charge_not_confirmed`與`result_pending_check`。若您的程式碼將`error.code`與舊值比較，請改為表格中的代碼；舊代碼與新代碼的對應關係可詢問[客服](https://ailoot.ai/docs/zh-hant-tw/support/)。 ## [](https://ailoot.ai/docs/zh-hant-tw/errors/#retry)何時重試請求 - **先查看 X-Should-Retry**：若為`false`，`result_pending_check`或`model_timeout` ，請勿自動重試。請在控制台歷史紀錄中查找 Request ID，其中可查看結果與扣款。 - **收到 X-Should-Retry: true 時，才可安全重試**：請等待`Retry-After`秒。對 5xx 而言，只有狀態碼並不足夠，結果可能已經產生。請先查看控制台歷史紀錄，或提供 Request ID 聯絡客服。影像、影片、音樂與較長的代理步驟，尤其需要注意。 - **重試無法解決**：400、401、402、403、404，請先修正請求、金鑰或餘額。 OpenAI與Anthropic SDK 通常會自動重試網路錯誤與5xx 錯誤。生成內容時，請停用此行為 (`max_retries=0`)，並在再次嘗試前檢查`X-Should-Retry`。回應遺失不代表請求未執行。 ## [](https://ailoot.ai/docs/zh-hant-tw/errors/#limits)限制 請求頻率與同時進行的請求數的限制，適用於整個帳戶，而非個別金鑰。超過限制時會收到 429 `rate_limit_exceeded`並包含標頭`Retry-After: 10`。若是模型本身過載，則為 503 `model_overloaded`包含`Retry-After: 30`。若需要處理更高負載，請聯絡[客服](https://ailoot.ai/docs/zh-hant-tw/support/)。 支出限制設定於金鑰：總上限對應 402 `api_key_quota_exhausted`，5 小時、1 天與7 天的時間視窗對應 429 `usage_limit_reached`。詳細說明請見[API 金鑰與位址](https://ailoot.ai/docs/zh-hant-tw/keys/#key)。 ## [](https://ailoot.ai/docs/zh-hant-tw/errors/#nvidia)NVIDIA 模型：佇列 即使餘額為零，也可查詢模型清單；生成則需要足夠餘額供保留金額使用。NVIDIA 模型 (Nemotron 等) 共用佇列，負載較高時，回應可能較晚抵達，或傳回「模型暫時過載」錯誤及 Retry-After 標頭，請等待指定時間後重試。價格請見目錄，扣款方式與其他模型相同。 大小限制由模型決定，包括上下文 (可傳送的 token 數)與回應的最大長度。這些資訊列於[目錄](https://ailoot.ai/models/zh-hant-tw/)。 ## 使用紀錄與費用 [使用紀錄與費用](https://ailoot.ai/usage) · [GET https://ailoot.ai/api/v1/usage](https://ailoot.ai/docs/zh-hant-tw/cabinet/usage/) · JWT · `Authorization: Bearer $TOKEN` `JWT ≠ sk-…` · [登入與工作階段](https://ailoot.ai/docs/zh-hant-tw/cabinet/auth/) 還有疑問嗎？請提供 Request ID與問題描述，我們會協助釐清。[聯絡支援](mailto:support@ailoot.ai) ## Ailoot · 公司及其專案組合 Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。 公司及其專案組合：數百萬客戶，每月銷售額達數十億。 Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。