API 错误

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

标准 API 错误代码

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

代码	HTTP Status	说明	建议采取的操作
`invalid_request`	400 无效请求	请求载荷格式不正确或包含无效参数。	请对照 API 参考文档检查请求语法和参数。
`failed_precondition`	400 无效请求	由于未满足前提条件（例如，停用了结算功能），因此无法处理请求。	验证项目结算状态或账号前提条件。
`out_of_range`	416 Requested Range Not Satisfiable	请求参数超出有效范围。	检查参数值和限制。
`parameter_unknown`	400 无效请求	请求包含未知参数。	请移除无法识别的参数，然后重试。
`authentication`	401 未经授权	API 密钥缺失、无效或已过期。	验证您的 API 密钥。
`payment_required`	402 Payment Required	您的预付款余额已用完。	请向您的结算账号充值，或开启自动充值。请勿重试：在添加赠金之前，请求不会成功。
`permission_denied`	403 禁止访问	您的 API 密钥无权访问此资源，或者您项目的 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 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`	回答中缺少必需的思考签名。

错误响应格式

Interactions API 返回的所有错误都会返回一个包含 code 和 message 的 error 对象。例如，传递不受支持的工具类型会返回：

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

后续步骤

API 问题排查：解决常见问题和错误场景。
速率限制：了解请求限制和配额处理。