API 错误

本页提供了 GenerateContent API 返回的后端错误代码的参考文档，介绍了 gRPC 错误响应格式，并提供了问题排查步骤。

HTTP 错误代码

下表列出了常见的后端错误代码、原因说明和建议的解决方案：

HTTP 代码 状态 说明 示例 解决方案
400 INVALID_ARGUMENT 请求正文格式不正确。 您的请求中存在拼写错误，或者缺少必填字段。 请查看 API 参考文档，了解请求格式、示例和支持的版本。使用较新 API 版本中的功能搭配较旧的端点可能会导致错误。
400 FAILED_PRECONDITION Gemini API 免费层级在您所在的国家/地区不可用。请在 Google AI Studio 中为您的项目启用结算功能。 您在不支持免费层级的区域发出请求，并且未在 Google AI Studio 中为您的项目启用结算功能。 如需使用 Gemini API，您需要使用 Google AI Studio 设置付费方案。
403 PERMISSION_DENIED 您的 API 密钥没有所需的权限。 您使用的 API 密钥不正确；您尝试使用经过微调的模型，但未经过 适当的身份验证。 检查您的 API 密钥是否已设置且具有正确的访问权限。请务必经过适当的身份验证，才能使用经过微调的模型。
404 NOT_FOUND 未找到所请求的资源。 未找到您的请求中引用的图片、音频或视频文件。 检查您的请求中的所有参数对于您的 API 版本是否有效。
429 RESOURCE_EXHAUSTED 您已超出 API 的速率限制之一（RPM、TPM、RPD、支出等）。 您发送的请求过多，使用的令牌过多，或者超出了您账号的账单历史记录和层级的支出限制。 验证您是否在模型的 速率限制 范围内。稍等片刻后重试。降低请求的速率或大小。如有需要，请申请提高速率限制。
499 CANCELLED 操作已取消（通常是被调用者取消）。 客户端在 API 完成响应之前关闭了连接。 检查您的客户端或网络基础架构是否过早关闭了连接（例如，由于客户端超时）。
500 INTERNAL Google 端发生了意外错误。 您的输入上下文过长。 查看 Gemini API 状态页面，了解是否有任何正在发生的事件。减少输入上下文，或暂时切换到其他模型（例如，从 Gemini 2.5 Pro 切换到 Gemini 2.5 Flash），看看是否有效。或者稍等片刻，然后重试请求。如果重试后问题仍然存在，请使用 Google AI Studio 中的发送反馈 按钮报告该问题。
503 UNAVAILABLE 服务可能暂时过载或关闭。 服务暂时容量不足。 查看 Gemini API 状态页面，了解是否有任何正在发生的事件。暂时切换到其他模型（例如，从 Gemini 2.5 Pro 切换到 Gemini 2.5 Flash），看看是否有效。或者稍等片刻，然后重试请求。如果重试后问题仍然存在，请使用 Google AI Studio 中的发送反馈 按钮报告该问题。
504 DEADLINE_EXCEEDED 服务无法在截止时间内完成处理。 您的提示（或上下文）过大，无法及时处理。 在客户端请求中设置更大的“超时”时间，以避免此错误。

错误响应格式

当 GenerateContent 请求失败时，API 会设置 HTTP 状态代码（例如 400 Bad Request、403 Forbidden 或 429 Too Many Requests），并返回包含 gRPC 状态详细信息的 JSON 响应正文：

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
字段 类型 说明
code integer HTTP 状态代码。
message string 人类可读的错误说明。
status string SCREAMING_CASE 中的 gRPC 状态代码。
details array 其他错误上下文，例如 ErrorInfo 或 LocalizedMessage。

后续步骤