API 錯誤

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

標準 API 錯誤代碼

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

程式碼 HTTP 狀態 說明 建議做法
invalid_request 400 錯誤的要求 要求酬載格式有誤或含有無效參數。 根據 API 參考資料檢查要求語法和參數。
failed_precondition 400 錯誤的要求 由於未符合必要條件 (例如帳單已停用)，因此無法處理要求。 確認專案帳單狀態或帳戶必要條件。
out_of_range 416 無法提供要求範圍內的內容 要求參數超出有效範圍。 檢查參數值和限制。
parameter_unknown 400 錯誤的要求 要求含有不明參數。 移除無法辨識的參數，然後重試。
authentication 未授權 401 API 金鑰遺失、無效或已過期。 驗證 API 金鑰。
payment_required 402 需要付費 預付抵免額餘額已用盡。 新增抵免額至帳單帳戶，或啟用自動儲值。請勿重試：必須先新增點數，要求才會成功。
permission_denied 403 Forbidden 您的 API 金鑰沒有這項資源的權限。 檢查 API 金鑰權限和專案存取權。
not_found 404 找不到網頁 找不到要求的資源。 確認資源路徑和參數。
model_not_found 404 找不到網頁 找不到指定的模型。 確認模型名稱或改用其他模型。
already_exists 409 Conflict 您嘗試建立的實體已存在。 重新建立資源前，請先檢查資源是否已存在。
aborted 409 Conflict 作業因發生衝突或並行檢查失敗而中止。 請在較高的應用程式層級重試要求。
rate_limit_exceeded 429 要求數量過多 您已超過每分鐘或每秒的要求或權杖限制。 請稍後再以指數輪詢方式重試。
quota_exceeded 429 要求數量過多 你已超過每日配額。 請等待配額重設，或申請提高配額。
too_many_requests 429 要求數量過多 你在短時間內發出過多要求。 請稍後再以指數輪詢方式重試。
cancelled 499 用戶端已結束要求 用戶端在要求完成前取消要求。 您不需要採取任何行動。這通常表示用戶端已中斷連線。
api_error 500 內部伺服器錯誤 伺服器發生未預期的錯誤。 請重試要求。如果問題仍未解決，請聯絡支援團隊。
unimplemented 501 尚未支援 作業或功能未實作或不支援。 檢查 API 功能或改用支援的功能。
service_unavailable 無法使用服務 503 服務暫時超載或關閉。 請稍後再以指數輪詢方式重試。
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 參考資料」。

後續步驟