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 禁止 | 您的 API 密钥缺少此资源的权限,或者您的项目受到限制或需要验证或计费更改。 | 检查您的 API 密钥权限, 验证状态和计费状态。参见 项目受限或不可用. |
not_found | 404 未找到 | 未找到请求的资源。 | 验证资源路径和参数。 |
model_not_found | 404 未找到 | 未找到指定型号。 | 验证型号名称或回退到其他型号。 |
already_exists | 409 冲突 | 您尝试创建的实体已存在。 | 重新创建之前检查资源是否已存在。 |
aborted | 409 冲突 | 由于冲突或并发检查失败,操作被中止。 | 在更高的应用程序级别重试该请求。 |
rate_limit_exceeded | 429 请求过多 | 您已超出每分钟或每秒请求或 token 限制。 | 等待并使用指数退避重试。 |
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 | 字符串 | 人类可读的错误描述。 |
错误是如何传递的 #
根据您发出标准 HTTP 请求还是流式 (SSE) 请求,API 会以不同方式传递错误。
标准 HTTP 请求 #
对于标准(非流)请求,API 设置 HTTP 响应状态代码(例如 400 Bad Request, 401 Unauthorized, 或 429 Too Many Requests)并返回一个 error JSON 响应正文中的对象:
{
"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 参考.