錯誤碼參考

錯誤回應通常同時包含 HTTP 狀態和回應本文中的程式錯誤碼。應用應先判斷 HTTP 狀態，再讀取實際回傳的 type、code 和 message；不同協議或上游回傳的欄位可能不同。

如果需要按現象疑難排解問題，請先閱讀錯誤與疑難排解。本頁用於查詢錯誤含義，不替代具體 Endpoint 的回應說明。

HTTP 狀態

HTTP 狀態	常見含義	常見原因	建議處理
`400`	請求無效	JSON、必填欄位、參數類型、檔案格式或輸入內容不符合要求	根據錯誤資訊修正請求，不直接重試
`401`	認證失敗	API Key 缺失、無效，或者身分驗證 Header 不符合協議要求	檢查 Bearer 或協議專屬 Header，並更換無效 Key
`403`	權限或額度不足	帳戶、Key、模型權限、IP 範圍或可用額度不滿足請求	檢查帳戶與 Key 的限制，確認目標模型可用
`404`	資源不存在	Endpoint、模型 ID、任務 ID 或 Video ID 不存在	核對最終 URL、資源 ID 和資源所屬帳戶
`429`	請求受到限制	請求頻率、併發、額度或服務容量達到限制	降低負載並在有限次數內重試；持續失敗時儲存 Request ID
`500`	請求處理失敗	請求轉換、Token 計算、定價資訊或平台處理發生異常	儲存去識別化錯誤資訊和 Request ID，稍後在有限次數內重試
`502`	上游閘道錯誤	上游回傳無效回應或閘道無法完成轉發	在有限次數內重試；持續失敗時聯絡技術支援
`503`	服務暫時不可用	平台或上游服務過載、維護或暫無處理容量	採用退避重試，不持續高頻請求
`504`	請求逾時	上游處理時間超過閘道等待時間	記錄 Request ID；非同步任務優先查詢原任務狀態

HTTP 狀態不能單獨確定原因

404 可能表示路徑、模型或任務不存在，429 也可能來自頻率、併發、額度或服務容量。應用應結合實際錯誤本文和 Request ID 判斷。

OpenAI 相容介面通常使用 error 物件承載錯誤資訊：

{
  "error": {
    "message": "請求失敗的具體原因",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

部分平台任務介面直接回傳 code 和 message：

{
  "code": "task_not_exist",
  "message": "查詢的任務 ID 不存在"
}

用戶端不應假設所有介面具有完全相同的錯誤格式。解析前請檢視對應 API Reference，並為缺失的可選欄位提供相容處理。

`code`	HTTP 狀態	客戶含義	建議處理
`1`	`200`	任務提交成功	儲存回傳的任務 ID，並透過查詢介面取得進度
`4`	`400`	請求參數錯誤	檢查 Prompt、操作類型和必填欄位
`21`	`200`	相同任務已經存在	繼續使用回傳的任務 ID，不要重複建立
`22`	`200`	任務正在排隊	保留任務 ID，稍後繼續查詢
`23`	`429`	目前任務佇列已滿	降低提交頻率並稍後重試
`24`	`400`	Prompt 未透過內容檢查	調整 Prompt 後重新提交
`3`	`403`	目前請求暫時無法提交	儲存錯誤資訊，稍後重試或聯絡技術支援
`30`	`429`	目前分組處理容量已滿	降低併發並稍後重試

任務提交成功範例：

{
  "code": 1,
  "description": "提交成功",
  "result": "TASK_ID"
}

任務排隊範例：

{
  "code": 22,
  "description": "排隊中，前面還有 2 個任務"
}

`code`	HTTP 狀態	客戶含義	建議處理
`task_not_exist`	`404`	任務不存在或不屬於目前帳戶	核對任務 ID、API Key 和請求端點
`quota_not_enough`	`403`	目前額度不足以建立任務	檢查帳戶與權杖額度，避免直接重試
`invalid_api_platform`	`400`	請求中的平台類型無效	修正平台或協議參數
`fail_to_fetch_task`	以上游狀態為準	無法從任務來源取得最新狀態	儲存目前任務 ID，稍後在有限次數內重試

`code`	常見 HTTP 狀態	客戶含義	建議處理
`invalid_request`	`400`	請求格式或參數無效	檢查 JSON、必填欄位和欄位類型
`read_request_body_failed`	`400`	請求本文無法讀取	檢查請求本文大小、連接和 Content-Type
`sensitive_words_detected`	`400`	輸入內容未透過內容檢查	調整輸入內容後重新傳送
`prompt_blocked`	`400`	Prompt 被內容策略攔截	根據錯誤資訊調整 Prompt
`access_denied`	`403`	目前請求被拒絕	檢查 API Key、帳戶狀態和允許的 IP 範圍
`insufficient_user_quota`	`403`	帳戶可用額度不足	檢查餘額或額度後再請求
`pre_consume_token_quota_failed`	`403`	Token 可用額度不足	檢查目前 Key 的額度和使用限制
`model_not_found`	`404`	目前帳戶無法找到目標模型	從模型廣場重新複製可用模型 ID
`convert_request_failed`	`500`	請求無法轉換為目標協議	核對 Endpoint、協議和目標模型相容性
`count_token_failed`	`500`	請求的 Token 用量無法計算	儲存去識別化請求特徵和 Request ID
`do_request_failed`	`500`	平台無法完成上游請求	檢查網路狀態並在有限次數內重試
`bad_response_status_code`	以上游狀態為準	上游回傳了非標準或無法直接解析的錯誤	儲存原 HTTP 狀態、去識別化訊息和 Request ID
`api_not_implemented`	`501`	目前 Endpoint 尚不可用	核對 API Reference，改用已經公開的 Endpoint

需要儲存追蹤資訊時參閱 Request ID，更完整的疑難排解與重試建議請參閱錯誤與疑難排解。