Gemini 中文指南
获取 API 密钥 ↗

API 错误

↓ 下载 Markdown

本页面提供所有 Interactions API 错误代码的参考,描述错误响应格式,并解释 API 如何针对不同请求类型传递错误。

标准 API 错误代码 #

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

代码HTTP 状态说明建议采取的行动
invalid_request400 错误请求请求负载格式错误或包含无效参数。检查您的请求语法和参数 API参考.
failed_precondition400 错误请求由于不满足先决条件(例如禁用计费),因此无法处理请求。验证项目计费状态或帐户先决条件。
out_of_range416 请求的范围无法满足请求参数超出有效范围。检查参数值和限制。
parameter_unknown400 错误请求该请求包含未知参数。删除无法识别的参数并重试。
authentication401 未经授权API 密钥丢失、无效或过期。验证您的 API 密钥.
payment_required402 需要付款您的预付款信用余额已耗尽。添加制作人员 到您的结算帐户,或打开 自动重新加载。不要重试:在添加积分之前请求不会成功。
permission_denied403 禁止您的 API 密钥缺少此资源的权限,或者您的项目受到限制或需要验证或计费更改。检查您的 API 密钥权限, 验证状态和计费状态。参见 项目受限或不可用.
not_found404 未找到未找到请求的资源。验证资源路径和参数。
model_not_found404 未找到未找到指定型号。验证型号名称或回退到其他型号。
already_exists409 冲突您尝试创建的实体已存在。重新创建之前检查资源是否已存在。
aborted409 冲突由于冲突或并发检查失败,操作被中止。在更高的应用程序级别重试该请求。
rate_limit_exceeded429 请求过多您已超出每分钟或每秒请求或 token 限制。等待并使用指数退避重试。
quota_exceeded429 请求过多您已超出每日配额。等待配额重置或请求增加配额。
too_many_requests429 请求过多您在短时间内提出了太多的要求。等待并使用指数退避重试。
cancelled499 客户端关闭请求客户端在请求完成之前取消了请求。无需采取任何行动。这通常意味着客户端已断开连接。
api_error500 内部服务器错误服务器发生意外错误。重试请求。如果问题仍然存在,请联系支持人员。
unimplemented501 未实施未实现或不支持该操作或功能。检查 API 功能或切换到支持的功能。
service_unavailable503服务不可用服务暂时超载或停机。等待并使用指数退避重试。
deadline_exceeded504 网关超时该请求未在截止日期内完成。删除或增加客户端截止时间设置以使用服务器默认值。

生成阻塞代码 #

这些错误代码表明策略、安全或内容限制阻止了模型的输出。当您收到这些代码之一时,请修改您的输入并重试。

代码说明
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。例如,传递不支持的工具类型会返回:

json
{
  "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 响应正文中的对象:

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 结构:

json
{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

有关完整的 SSE 事件架构,请参阅 Interactions API 参考.

后续步骤 #

搜索标题、API 名称或正文内容