API 錯誤

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

標準 API 錯誤代碼

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

程式碼 HTTP 狀態 說明 建議做法
invalid_request 400 錯誤的要求 要求格式有誤或含有無效參數。 根據 API 參考資料檢查輸入內容。
parameter_unknown 400 錯誤的要求 要求含有不明參數。 移除無法辨識的參數，然後重試。
authentication 未授權 401 API 金鑰遺失或無效。 驗證 API 金鑰。
permission_denied 403 Forbidden 您的 API 金鑰沒有這項資源的權限。 檢查 API 金鑰權限和專案存取權。
not_found 404 找不到網頁 找不到要求的資源。 確認資源路徑和參數。
model_not_found 404 找不到網頁 找不到指定的模型。 確認模型名稱或改用其他模型。
rate_limit_exceeded 429 要求數量過多 您已超過每分鐘或每秒的要求或權杖限制。 請稍後再以指數輪詢方式重試。
quota_exceeded 429 要求數量過多 你已超過每日配額。 請等待配額重設，或申請提高配額。
cancelled 499 用戶端已結束要求 用戶端在要求完成前取消要求。 您不需要採取任何行動。這通常表示用戶端已中斷連線。
api_error 500 內部伺服器錯誤 伺服器發生未預期的錯誤。 請重試要求。如果問題仍未解決，請聯絡支援團隊。
service_unavailable 無法使用服務 503 服務暫時超載或關閉。 請稍後再以指數輪詢方式重試。

生成封鎖代碼

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

程式碼 說明
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 參考資料」。

後續步驟