API 错误

本页提供了所有 Interactions API 错误代码的参考文档，介绍了错误响应格式，并说明了 API 如何针对不同请求类型传递错误。

标准 API 错误代码

这些常规请求级错误代码对应于标准 HTTP 状态代码。 您可以使用应用逻辑中的 code 字段以编程方式处理错误。

代码 HTTP Status 说明 推荐措施
invalid_request 400 Bad Request 请求格式有误或包含无效参数。 请对照 API 参考文档 检查您的输入。
parameter_unknown 400 Bad Request 请求包含未知参数。 请移除无法识别的参数，然后重试。
authentication 401 Unauthorized API 密钥缺失或无效。 请验证您的 API 密钥。
permission_denied 403 Forbidden 您的 API 密钥没有此资源的权限。 请检查您的 API 密钥权限和项目访问权限。
not_found 404 Not Found 找不到所请求的资源。 请验证资源路径和参数。
model_not_found 404 Not Found 找不到指定的模型。 请验证模型名称或回退到其他模型。
rate_limit_exceeded 429 Too Many Requests 您已超出每分钟或每秒的请求或令牌限制。 请等待一段时间并使用指数退避算法重试。
quota_exceeded 429 Too Many Requests 您已超出每日配额。 请等待配额重置或申请增加配额。
cancelled 499 Client Closed Request 客户端在请求完成之前取消了请求。 您无需执行任何操作。这通常意味着客户端已断开连接。
api_error 500 Internal Server Error 服务器上发生意外错误。 请重试该请求。如果问题仍然存在，请与支持团队联系。
service_unavailable 503 Service Unavailable 服务暂时过载或关闭。 请等待一段时间并使用指数退避算法重试。

生成被阻止代码

这些错误代码表示政策、安全或内容限制阻止了模型的输出。当您收到其中一个代码时，请修改输入并重试。

代码 说明
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 响应缺少必需的 thought 签名。

错误响应格式

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 参考文档。

后续步骤