跳至主要內容

指南

錯誤

錯誤格式與全部錯誤類型。

{
  "error": {
    "type": "session_running",
    "message": "Session 'ses_8d0f…' is running a turn.",
    "request_id": "6f1c2e0a9b8d4c7e8f3a2b1c0d9e8f7a"
  }
}
  • type：穩定的錯誤類型，程式判斷請用它，不要匹配 message 的文字。
  • message：給人看的說明，內容可能調整。
  • details：可選的附加資訊。例如參數驗證錯誤時是出錯欄位的列表，模型不可用時是可用模型的列表。
  • request_id：請求 ID，同時在回應頭 X-Request-ID 中返回。聯絡我們排查問題時請提供它。

參數驗證錯誤範例：

{
  "error": {
    "type": "validation_error",
    "message": "The request failed validation.",
    "details": [
      {"location": ["body", "content"], "message": "String should have at least 1 character", "type": "string_too_short"}
    ],
    "request_id": "…"
  }
}

錯誤類型

狀態碼type說明
400bad_request上載請求中不止一個檔案或欄位；每次只能上載一個檔案。
401invalid_api_key缺少 API Key，或 Key 無效、已撤銷、已過期。
403insufficient_scopeKey 有效，但缺少所需權限。
404session_not_found會話不存在、已刪除或屬於其他項目。
404file_not_found檔案不存在、已刪除或屬於其他項目。
404skill_not_found技能不存在、已刪除或屬於其他項目。
404mcp_server_not_foundMCP 伺服器不存在、已刪除或屬於其他項目。
409skill_name_taken項目中已有同名技能。
409mcp_server_name_taken項目中已有同名 MCP 伺服器。
409mcp_server_url_taken項目中已註冊了同一個 MCP 地址。
404not_found請求的路徑不存在。
405method_not_allowed該路徑不支援此 HTTP 方法。
409session_running會話正在執行一輪，不能發送訊息或刪除。
413content_too_large請求體超過上限：上載檔案約 100 MiB，其他接口 1 MiB。
413file_too_large上載的檔案超過 100 MiB。
413skill_bundle_too_large技能包超過 50 MiB，或解壓後過大。
422validation_error請求參數不合法，詳情見 details。
422unknown_model模型不可用，details 中列出可用模型。
422metadata_too_large合併後的 metadata 超過 16 對。
422invalid_cursor分頁游標格式錯誤。
422invalid_filename上載的檔名不可用。
422invalid_skill_bundle不是可用的技能包，message 說明原因。
422invalid_mcp_server_urlMCP 地址不是 https，或指向非公網地址。
422mcp_probe_failed探測 MCP 伺服器失敗，message 說明原因。
422unknown_mcp_toolallowed_tools 裡有伺服器沒有的工具。
429rate_limited超過限流。等待 Retry-After 回應頭給出的秒數後重試。
429too_many_running_turns項目中同時排隊和執行的輪次已達上限。等任意一輪結束後再發送訊息。
500internal_server_error伺服器端錯誤，可以重試；持續出現請聯絡我們，並提供 request_id。
502storage_error檔案儲存暫時不可用，可以重試。

建議對 429 和 5xx 做帶退避的重試；遇到 too_many_running_turns 時，更好的做法是等自己的某一輪結束後再發。除 429 外的 4xx 重試沒有意義，請先修正請求。