API 错误

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

标准 API 错误代码

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

代码 HTTP Status 说明 推荐措施
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 未经授权 API 密钥缺失、无效或已过期。 验证您的 API 密钥。
permission_denied 403 禁止访问 您的 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 Client Closed Request 客户端在请求完成之前取消了请求。 您无需执行任何操作。这通常意味着客户端已断开连接。
api_error 500 内部服务器错误 服务器上发生意外错误。 重试请求。如果问题仍然存在，请与支持团队联系。
unimplemented 501 Not Implemented 操作或功能未实现或不受支持。 检查 API 功能或切换到受支持的功能。
service_unavailable 503 Service Unavailable 服务暂时过载或关闭。 等待一段时间并使用指数退避算法重试。
deadline_exceeded 504 Gateway Timeout 请求未在截止期限内完成。 移除或增加客户端截止期限设置以使用服务器默认值。

生成被阻止代码

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

代码 说明
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 参考文档。

后续步骤