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 设置付费方案。
402 RESOURCE_EXHAUSTED 您的预付款余额已用完。 您的结算账号的预付款用完了，因此与该结算账号关联的每个 API 密钥都停止了工作。 向结算账号添加点数，或开启自动充值。请勿重试此请求：在添加积分之前，此请求不会成功。
403 PERMISSION_DENIED 您的 API 密钥没有所需的权限。 您使用的 API 密钥有误；您尝试使用经过调优的模型，但未通过正确的身份验证。 检查您的 API 密钥是否已设置且拥有适当的访问权限。请务必完成适当的身份验证，才能使用调整后的模型。
404 NOT_FOUND 找不到所请求的资源。 未找到您的请求中引用的图片、音频或视频文件。 检查请求中的所有参数是否对您的 API 版本有效。
429 RESOURCE_EXHAUSTED 您已超出某个 API 的速率限制（RPM、TPM、RPD、支出等）。 您发送的请求过多、使用的令牌过多，或者超出了账号的账单历史记录和层级对应的支出限额。 验证您是否在模型的速率限制范围内。稍等片刻后重试。降低请求速率或减小请求大小。如有需要，请申请提高速率限制。
499 已取消 操作已取消（通常是被调用者取消）。 在 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 字符串 人类可读的错误说明。
status 字符串 SCREAMING_CASE 中的 gRPC 状态代码。
details 数组 其他错误上下文，例如 ErrorInfo 或 LocalizedMessage。

后续步骤