API 錯誤

本頁面提供所有 Interactions API 錯誤代碼的參考資料、說明錯誤回應格式，以及 API 如何針對不同要求類型傳送錯誤。

Standard API 錯誤代碼

這些一般要求層級錯誤代碼對應至標準 HTTP 狀態碼。在應用程式邏輯中使用 code 欄位，以程式輔助方式處理錯誤。

程式碼 HTTP 狀態 說明 建議做法
invalid_request 400 Bad Request 要求酬載格式錯誤或包含無效參數。 請參閱 API 參考資料，檢查要求語法和參數。
failed_precondition 400 Bad Request 未符合必要條件 (例如停用計費功能)，因此無法處理要求。 確認專案帳單狀態或帳戶必要條件。
out_of_range 416 Requested Range Not Satisfiable 要求參數超出有效範圍。 請檢查參數值和限制。
parameter_unknown 400 Bad Request 要求含有不明參數。 請移除無法辨識的參數，然後再試一次。
authentication 401 Unauthorized API 金鑰遺失、無效或已過期。 驗證 API 金鑰。
payment_required 402 Payment Required 您的預付抵免餘額已用盡。 請在帳單帳戶中新增抵免額，或開啟自動儲值功能。請勿重試：必須先新增抵免額，要求才會成功。
permission_denied 403 禁止存取 您的 API 金鑰沒有這項資源的權限，或專案的 API 存取權受限。 請檢查 API 金鑰權限、專案級別資格和帳單狀態。請參閱「排解專案受限或無法使用的問題」。
not_found 找不到 404 找不到要求的資源。 請確認資源路徑和參數。
model_not_found 找不到 404 找不到指定的模型。 請確認模型名稱，或改用其他模型。
already_exists 409 衝突 您嘗試建立的實體已存在。 重新建立前，請先確認資源是否已存在。
aborted 409 衝突 由於發生衝突或並行檢查失敗，作業已中止。 請在較高的應用程式層級重試要求。
rate_limit_exceeded 429 要求數量過多 您已超過每分鐘或每秒的要求或權杖限制。 請稍後再以指數輪詢方式重試。
quota_exceeded 429 Too Many Requests 已超過每日配額。 請等待配額重設，或申請提高配額。
too_many_requests 429 Too Many Requests 您在短時間內提出的要求過多。 請稍後再以指數輪詢方式重試。
cancelled 499 Client Closed Request 用戶端在要求完成前取消。 您無須採取任何行動。這通常表示用戶端已中斷連線。
api_error 500 內部伺服器錯誤 伺服器發生未預期的錯誤。 重試要求。如果問題仍未解決，請與支援團隊聯絡。
unimplemented 501 Not Implemented 未實作或不支援這項作業或功能。 請檢查 API 功能，或改用支援的功能。
service_unavailable 503 Service Unavailable 服務暫時超載或停機。 請稍後再以指數輪詢方式重試。
deadline_exceeded 504 閘道逾時 要求未在期限內完成。 移除或提高用戶端期限設定，改用伺服器預設值。

生成作業阻斷程式碼

這些錯誤代碼表示政策、安全或內容限制封鎖了模型輸出內容。收到這類代碼時，請修改輸入內容並重試。

程式碼 說明
safety 要求因違反安全政策 (有害內容) 而遭封鎖。
recitation 著作權或朗誦限制導致要求遭拒。
language 要求因不支援的語言而遭封鎖。
prohibited_content 要求因違反禁止內容規範而遭封鎖。
spii 具敏感性的個人識別資訊限制封鎖了要求。
blocklist 要求因含有封鎖清單中的違禁字詞而遭封鎖。
image_safety 違反安全政策，因此無法生成圖像。
image_prohibited_content 禁止宣傳的內容規範封鎖了圖像生成。
image_recitation 著作權或背誦限制導致無法生成圖像。
image_other 因不明原因而無法生成圖像。
content_blocked 要求因不明政策原因而遭封鎖。

生成錯誤代碼

這些錯誤代碼表示模型生成的輸出內容有結構性問題，例如函式呼叫格式錯誤，或工具呼叫未宣告。

程式碼 說明
malformed_function_call 模型產生的函式呼叫無法剖析。
malformed_tool_call 模型產生的工具呼叫無法剖析。
unexpected_tool_call 模型呼叫了要求中未宣告的工具。
no_image 模型無法生成圖片。
too_many_tool_calls 模型產生的工具呼叫數量超過允許上限。
missing_thought_signature 回覆缺少必要的思考簽章。

錯誤回應格式

Interactions API 的所有錯誤都會傳回 error 物件，其中包含 code 和 message。舉例來說，傳遞不支援的工具類型會傳回：

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
欄位 類型 說明
code 字串 snake_case 中的機器可讀錯誤代碼。
message 字串 人類可讀的錯誤原因說明。

錯誤傳送方式

API 傳送錯誤的方式，取決於您提出的是標準 HTTP 要求，還是串流 (SSE) 要求。

標準 HTTP 要求

如果是標準 (非串流) 要求，API 會設定 HTTP 回應狀態碼 (例如 400 Bad Request、401 Unauthorized 或 429 Too Many Requests)，並在 JSON 回應主體中傳回 error 物件：

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

串流 (SSE) 要求

如果是串流要求 (stream: true)，API 會透過伺服器傳送事件 (SSE) 串流傳送錯誤事件，並將 event_type 設為 "error"。error 欄位包含相同的 code 和 message 結構：

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

如需完整的 SSE 事件結構定義，請參閱 Interactions API 參考資料。

後續步驟