> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 錯誤碼速查

> 查閱 API 請求錯誤與任務失敗原因, 依具體情況修正輸入或復原請求

先區分請求失敗與任務執行失敗, 再查錯誤識別碼與說明. `invalid_request` 可能代表圖片尺寸不符要求, 不能據此判斷模型不支援圖片輸入.

## 從哪裡讀取錯誤

| 情境 | 判斷方式 | 讀取欄位 |
| - | - | - |
| OpenAI 格式的請求錯誤 | HTTP 非成功狀態或回應包含錯誤物件 | `error.code`, `error.message`, 選用的 `error.param` 與 `error.type` |
| 部分任務提交或查詢端點的請求錯誤 | 同時檢查 HTTP 狀態與回應內容 | 頂層 `code`, `message`, `data` |
| 任務執行失敗 | 查詢成功, 但任務 `status` 為 `failed` | `error.code`, 選用的 `error.reason`, `error.message` |
| 任務 Webhook 失敗事件 | `type` 為 `generation.failed`, `data.status` 為 `FAILURE` | `data.error.code`, `data.error.message` |
| 影片請求復原 | 檢查復原紀錄的 `state` | 選用的 `error_code`, `message`, `task_id` |

請求錯誤範例, 訊息僅供說明:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "type": "toapis_error",
    "param": "",
    "message": "Image dimensions or aspect ratio do not meet this model's requirements."
  }
}
```

任務執行失敗範例:

```json theme={null}
{
  "id": "task_example",
  "object": "generation.task",
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "reason": "image_dimensions_multiple",
    "message": "Image dimensions must be multiples of 16."
  }
}
```

範例中的倍數不是所有模型的共同限制. HTTP 200 只表示查詢成功, 仍需檢查任務狀態. 數字業務 `code` 也不等於 HTTP 狀態; 回應為 `success: false` 時需要檢查內容.

`code` 識別錯誤, 選用的 `reason` 補充任務失敗類別, `message` 說明具體情況. `error.type` 不一定等於錯誤碼. 訊息可能隨語言改變, 不要以完整訊息比對控制業務邏輯. 部分驗證回應的 `code` 為空, 部分協定只有 `type` 與 `message`.

## 請求錯誤速查

以下識別碼可能出現在公開請求中, 不是每個端點都會傳回全部項目. 模型也可能保留不同的原始拼寫. 欄位位置依上表讀取.

| 錯誤識別碼 | 可能情況 | 建議處理 |
| - | - | - |
| `invalid_request`, `invalid_request_error`, `invalid_params`, `InvalidParameter`, `invalid_parameter_error`, `invalid_value` | 參數型別, 圖片尺寸, 素材讀取, 訊息結構或參數組合不合法 | 依 `param` 與 `message` 找出問題欄位, 參考下方情況修正後再提交 |
| `invalid_json`, `invalid_multipart_form`, `read_request_body_failed` | JSON 或表單無法解析, 請求內容讀取失敗 | 檢查序列化結果, `Content-Type` 與上傳是否完整 |
| `unknown_parameter`, `unsupported_value`, `provider_capability_not_supported`, `not_supported` | 模型不接受某個欄位, 參數值, 工具或端點能力 | 查閱該模型說明, 移除不支援的欄位或改用支援該能力的模型 |
| `missing_model`, `model_not_found`, `unsupported_model`, `DeploymentNotFound` | 缺少模型名稱, 模型無法存取, 端點不支援或服務暫時無法使用 | 核對[模型目錄](https://docs.toapis.com/docs/zh-Hant/api-reference/models.md)與 API Key 權限. 名稱正確但訊息提示暫時無法使用時, 稍後重試或聯絡支援 |
| `invalid_private_assets`, `invalid_image`, `invalid_image_file` | 素材參照無效, 圖片無法解碼, 數量或尺寸超限, 或網址無法讀取 | 檢查指定素材與限制, 重新匯出或上傳後再提交 |
| `access_denied`, 或 HTTP 401/403 且沒有 code | API Key 無效, 過期, 停用, 或 IP 與模型權限受限 | 檢查金鑰與存取權限. 服務傳回的驗證錯誤不一定代表本機使用的金鑰有誤 |
| `insufficient_user_quota`, `quota_not_enough`, `token_quota_not_enough`, `pre_consume_token_quota_failed` | 帳戶餘額, Token 額度或週期限額不足; 額度檢查也可能暫時失敗 | 只有訊息明確指出本帳戶或 Token 時才儲值或調整額度. 服務端額度或檢查問題請稍後重試或聯絡支援 |
| `rate_limit_exceeded`, `RateLimitReached`, `rate_limit_unavailable` | 請求頻率超限, 模型服務限流或暫時無法檢查限額 | 降低並行量, 優先遵守 `Retry-After`, 再使用帶隨機延遲的退避. 見[非同步限流](https://docs.toapis.com/docs/zh-Hant/api-reference/rate-limits/async-tasks.md) |
| `get_channel_failed`, `all_channels_circuit_broken`, `provider_unavailable` | 模型目前沒有可用服務或負載過高 | 稍後重試, 持續失敗時聯絡支援, 不需要修改圖片內容 |
| `do_request_failed`, `first_output_timeout`, `up_timeout` | 連線, 等待首次輸出或讀取回應逾時; 請求可能已被受理 | 已有任務 ID 時先查詢該任務; 無 ID 的影片請求依下方流程復原 |
| `bad_response_status_code`, `bad_response`, `bad_response_body`, `read_response_body_failed`, `upstream_error`, `unknown_error` | 服務傳回錯誤或回應無法讀取, 解析 | 結合 HTTP 狀態與訊息判斷, 先確認是否已有任務. 持續失敗時提供請求 ID 聯絡支援 |
| `convert_request_failed`, `model_price_error`, `pricing_failed`, `pricing_unavailable`, `internal_error` | 請求轉換, 定價或服務處理失敗, 不一定是輸入錯誤 | 有明確欄位限制時修正輸入, 否則稍後重試或聯絡支援 |
| `task_not_found`, `task_not_exist`, `request_not_found` | 任務或復原紀錄不存在, 不屬於目前帳戶, 或復原紀錄已過期 | 核對 ID, 帳戶與查詢端點. 找不到復原紀錄不代表原請求從未執行 |
| `invalid_client_request_id`, `request_cache_unavailable`, `submission_unconfirmed` | 復原 ID 無效, 復原服務無法使用或提交結果尚未確認 | 修正 ID 格式或等待並查詢原請求, 不要連續建立新 ID 重送 |
| `invalid_callback_url`, `callback_url_origin_mismatch`, `webhook_not_configured`, `webhook_configuration_invalid`, `webhook_configuration_unavailable`, `webhook_configuration_error`, `webhook_api_token_required` | 回呼網址或 Token 的 Webhook 設定不符要求, 或暫時無法讀取設定 | 依[任務 Webhook](https://docs.toapis.com/docs/zh-Hant/api-reference/webhooks/task-webhooks.md)檢查 HTTPS, 來源, API Token 與設定 |
| `sensitive_words_detected`, `prompt_blocked`, `content_policy_violation`, `content_filter`, `content_filtered` | 輸入或生成結果未通過內容審核 | 檢查提示詞與全部參考素材, 修改為合規內容後再提交, 不要自動重送原請求 |
| `invalid_encrypted_content` | 對話輸出項目的加密內容無法驗證或解析 | 檢查用戶端是否修改或截斷歷史輸出項目, 保持這類項目原樣. 持續失敗時聯絡支援, 不要修改加密內容 |

## invalid\_request 可能具體指什麼

以下情況歸納自實際請求與失敗任務診斷, 可能由通用參數碼包裝, 或以具體 `reason` 與模型原始錯誤碼傳回. 先看欄位與具體說明, 再決定修改什麼.

| 具體情況 | 如何判斷與修正 |
| - | - |
| 輸出尺寸或比例的寫法不符 | 有些模型的 `size` 接受 `1:1` 等比例, 有些接受像素尺寸. 對只接受比例的模型傳入 `1024x1024` 會失敗. 依該模型的 `size`, `resolution`, `aspect_ratio` 定義傳值 |
| 寬高, 總像素或尺寸倍數不符 | 圖片可能太小, 太大, 比例過寬或寬高不是要求的倍數. 先區分參考圖與輸出尺寸, 再依該模型限制縮放或裁切 |
| 參考圖檔案或數量超限 | 檔案位元組數, 長邊像素, 總像素與圖片數量是不同限制. 壓縮檔案未必減少像素, 請依錯誤選擇壓縮, 縮放或減少圖片 |
| 圖片欄位型別錯誤 | 需要 URL 字串陣列的端點無法接受物件陣列. `image_urls` 與 `image_with_roles` 結構不同, 部分端點也不接受 Base64 或同時使用兩個欄位 |
| 網址存在但服務無法讀取檔案 | 403/404, 需要登入, 網址過期, 下載逾時, 防盜連或傳回 HTML 都可能造成失敗. 提供有效時間足夠的公開直接下載網址, 或先使用[上傳端點](https://docs.toapis.com/docs/zh-Hant/api-reference/uploads/images.md) |
| 素材格式或時長不符 | 副檔名正確不代表內容可解碼. GIF, 影片編碼, 幀率, 單段或總參考時長可能不符模型要求, 請依文件重新匯出 |
| Seedance 任務類型與參數衝突 | 影片編輯可能要求 `aspect_ratio=adaptive`, `duration=-1`; 延長也可能要求 `adaptive`. `InvalidParameter.TaskTypeConstraint` 也可能表示提示詞與素材被判定為另一任務類型. 見[Seedance 2.5](https://docs.toapis.com/docs/zh-Hant/api-reference/videos/seedance-2-5/generation.md) |
| 文字, 對話歷史或工具順序錯誤 | 提示詞過長, 模型不接受 `developer` 角色, `tool_calls` 缺少對應工具回覆或思考模式缺少 `reasoning_content`. 依模型協定修正 |
| 欄位存在但模型不接受 | `quality`, `reasoning_effort`, `temperature`, `thinking`, `enable_thinking` 並非通用欄位或值. `max_tokens` 與 `max_completion_tokens` 可能互斥. 工具 Schema 與 `response_format` 也需符合模型要求 |

歷史失敗中的數值不是全平台限制. 能否傳圖片要看模型能力, 不能只根據 `invalid_request` 或 `invalid_image` 判斷.

## 任務失敗原因速查

取得任務 ID 後以查詢狀態為準. 一般生成失敗常見 `error.code=generation_failed`, 具體類別讀取選用的 `error.reason`. 以下是 reason 值, 不保證出現在請求錯誤的 code 欄位.

若提供 `error.input_media_errors`, 逐項讀取 `type`, `index`, `message`. 例如 `type=image`, `index=0` 表示原請求的第一張圖片, 可針對該素材修正. 不是所有模型或查詢格式都提供這些明細.

| error.reason | 可能情況與處理 |
| - | - |
| `invalid_input`, `missing_parameter` | 輸入無效或缺少欄位. 依具體情況與訊息修正後再提交 |
| `reference_image_too_large`, `image_dimensions_multiple` | 參考圖檔案過大或像素尺寸不符倍數要求. 分別檢查檔案大小與尺寸 |
| `reference_media_unreadable`, `unsupported_media_format` | 網址無法下載, 檔案無效或格式不支援. 檢查存取權限與實際媒體內容 |
| `unsupported_parameter_value`, `parameter_out_of_range`, `parameter_replacement_required` | 參數值不在允許集合或範圍, 或需要替換欄位. 依訊息與模型說明修改 |
| `video_edit_parameters_required`, `unsupported_request_capability` | 編輯參數組合不合法或模型不支援該能力. 調整任務類型, 參數或模型 |
| `content_policy_rejected` | 提示詞, 參考圖片/影片/音訊或生成輸出未通過安全或版權審核. 檢查全部輸入; 合規輸入也可能因輸出審核而失敗 |
| `service_busy`, `request_rate_limited` | 服務繁忙或限流. 等待並降低請求頻率 |
| `generation_timeout` | 生成或任務處理逾時. 先確認既有任務狀態, 處理中不要反覆重新生成 |
| `generation_unavailable`, `model_unavailable`, `model_region_unavailable` | 模型服務暫時無法使用或目前區域不支援. 核對模型與權限, 持續異常時聯絡支援 |
| `insufficient_user_balance`, `token_quota_exceeded` | 本帳戶餘額或 API Token 額度不足. 檢查兩者與週期限額 |
| `result_storage_failed` | 結果儲存或交付失敗, 不一定是模型不支援輸入. 提供任務 ID 聯絡支援 |
| `submission_pending_reconciliation` | 提交或生成結果仍待確認. 保留既有 ID 並等待查詢結果, 避免重複生成 |
| `refund_pending` | 失敗任務的退款尚在處理. 查詢最新可用的計費狀態, 持續異常時聯絡支援 |
| `request_cancelled` | 請求或任務已取消. 確認是否符合預期後再決定重新提交 |
| `generation_failed`, `service_error` | 沒有更具體的公開原因或服務內部處理失敗. 保留任務與請求 ID 聯絡支援 |

部分模型保留 `InvalidParameter.TaskTypeConstraint`, `RateLimitReached`, `InputImageSensitiveContentDetected`, `OutputVideoSensitiveContentDetected` 等原始錯誤, 分別可能涉及任務參數, 限流, 輸入審核或輸出審核. 這不是完整清單.

Seedance Global 查詢的 `error.code` 與 `error.message` 可保留原始 JSON 值, 包括數字或 `null`, 也可能省略. OpenAI 影片格式與 Webhook 不保證提供 `reason`. 用戶端需接受未知錯誤碼, 缺省欄位與不同型別; 原始數字 code 不是 HTTP 狀態.

## 重試與請求復原

* 參數, 格式與內容審核問題: 修正輸入後再提交, 原樣重試通常無法解決.
* 限流或暫時無法使用: 優先遵守 `Retry-After`; 否則使用指數退避與隨機延遲, 並限制重試次數.
* 已有任務 ID: 繼續查詢該任務或接收[任務 Webhook](https://docs.toapis.com/docs/zh-Hant/api-reference/webhooks/task-webhooks.md). `queued` 與 `in_progress` 不是失敗, 不要因此建立重複任務.
* 影片提交逾時或 `submission_unconfirmed`: 原請求有使用 `client_request_id` 時, 以相同帳戶呼叫 `GET /v1/video/requests/{client_request_id}`. 取得 `task_id` 後查詢任務; `submitting` 或 `unknown` 表示繼續等待. 只有復原紀錄為 `failed` 且 `error_code=submission_rejected` 才能確認拒絕, 並依提示提出新請求. 此功能只適用於支援且使用該欄位的影片端點.

任務失敗不代表退款已完成. 查閱[計費狀態](https://docs.toapis.com/docs/zh-Hant/api-reference/account/pricing.md)中可用的 `billing` 欄位; 缺省不代表免費或退款完成. Webhook 是事件快照, 計費欄位可能與後續查詢不同.

## 聯絡支援時提供什麼

提供請求時間與時區, 模型, 端點, HTTP 狀態, 請求 ID, 可用的任務 ID, code/reason 與已去除敏感資訊的說明. 圖片問題提供尺寸, 格式與檔案大小即可. 不要傳送 API Key, 簽署網址, 完整提示詞或私人素材; 需要重現時使用可公開的最小範例.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.