錯誤碼速查

先區分請求失敗與任務執行失敗, 再查錯誤識別碼與說明. 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`

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

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

任務執行失敗範例:

{
  "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`	缺少模型名稱, 模型無法存取, 端點不支援或服務暫時無法使用	核對模型目錄與 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`, 再使用帶隨機延遲的退避. 見非同步限流
`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, 來源, 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 都可能造成失敗. 提供有效時間足夠的公開直接下載網址, 或先使用上傳端點
素材格式或時長不符	副檔名正確不代表內容可解碼. GIF, 影片編碼, 幀率, 單段或總參考時長可能不符模型要求, 請依文件重新匯出
Seedance 任務類型與參數衝突	影片編輯可能要求 `aspect_ratio=adaptive`, `duration=-1`; 延長也可能要求 `adaptive`. `InvalidParameter.TaskTypeConstraint` 也可能表示提示詞與素材被判定為另一任務類型. 見Seedance 2.5
文字, 對話歷史或工具順序錯誤	提示詞過長, 模型不接受 `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. queued 與 in_progress 不是失敗, 不要因此建立重複任務.
影片提交逾時或 submission_unconfirmed: 原請求有使用 client_request_id 時, 以相同帳戶呼叫 GET /v1/video/requests/{client_request_id}. 取得 task_id 後查詢任務; submitting 或 unknown 表示繼續等待. 只有復原紀錄為 failed 且 error_code=submission_rejected 才能確認拒絕, 並依提示提出新請求. 此功能只適用於支援且使用該欄位的影片端點.

任務失敗不代表退款已完成. 查閱計費狀態中可用的 billing 欄位; 缺省不代表免費或退款完成. Webhook 是事件快照, 計費欄位可能與後續查詢不同.

聯絡支援時提供什麼

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

快速上手

模型目錄

文本對話系列

圖像系列

視頻系列

音樂系列

任務管理

文件上傳

賬戶

常見問題

從哪裡讀取錯誤

請求錯誤速查

invalid_request 可能具體指什麼

任務失敗原因速查

重試與請求復原

聯絡支援時提供什麼

​從哪裡讀取錯誤

​請求錯誤速查

​invalid_request 可能具體指什麼

​任務失敗原因速查

​重試與請求復原

​聯絡支援時提供什麼

從哪裡讀取錯誤

請求錯誤速查

invalid_request 可能具體指什麼

任務失敗原因速查

重試與請求復原

聯絡支援時提供什麼