Gemini 中文指南
获取 API 密钥 ↗

API 错误

↓ 下载 Markdown

此页面提供了由返回的后端错误代码的参考 GenerateContent API,描述 gRPC 错误响应格式,并提供故障排除步骤。

HTTP 错误代码 #

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

HTTP 代码状态说明示例解决方案
400INVALID_ARGUMENT请求正文格式错误。您的请求中存在拼写错误或缺少必填字段。检查 API参考 有关请求格式、示例和支持的版本。将较新的 API 版本的功能与较旧的端点一起使用可能会导致错误。
400FAILED_PRECONDITIONGemini API 免费套餐在您所在的国家/地区不可用。请在 Google AI Studio 中为您的项目启用计费。您在不支持免费套餐的区域发出请求,并且您尚未在 Google AI Studio 中的项目上启用计费。要使用 Gemini API,您需要使用以下方法设置付费计划 Google AI Studio.
402RESOURCE_EXHAUSTED您的预付款信用余额已耗尽。您的计费帐户已用完预付积分,因此链接到该计费帐户的每个 API 密钥都会停止工作。添加制作人员 到您的结算帐户,或打开 自动重新加载。不要重试此请求:在添加积分之前它不会成功。
403PERMISSION_DENIED您的 API 密钥缺乏所需的权限,或者您的项目受到限制或需要验证或计费更改。您使用了错误的、被阻止的或泄漏的 API 密钥,或者调整后的模型需要 认证。您的项目需要移动设备验证,或者受到限制或不符合免费套餐的资格。您的结算帐户可能还有未付余额。检查您的 API 密钥是否处于活动状态、完整 项目验证,或查看帐单 Google AI Studio。参见 项目受限或不可用.
404NOT_FOUND未找到请求的资源。找不到您请求中引用的图像、音频或视频文件。检查请求中的所有参数对于您的 API 版本是否有效。
429RESOURCE_EXHAUSTED您已超出 API 的速率限制之一(RPM、TPM、RPD、支出等)。您发送了太多请求,使用了太多 token,或者超出了您帐户的账单历史记录和等级的基于支出的限制。验证您是否在模型范围内 速率限制。等待一段时间后重试。降低请求的速率或大小。 请求提高速率限制 如果需要的话。
499CANCELLED操作通常被调用者取消。客户端在 API 完成响应之前关闭了连接。检查您的客户端或网络基础设施是否过早关闭连接(例如,由于客户端超时)。
500INTERNALGoogle 方面发生意外错误。您的输入上下文太长。检查 Gemini API状态页 对于任何正在发生的事件。减少输入上下文或暂时切换到另一个模型(例如从 Gemini 2.5 Pro 到 Gemini 2.5 Flash)并查看它是否有效。或者稍等一下,然后重试您的请求。如果重试后问题仍然存在,请使用 发送反馈 Google AI Studio 中的按钮。
503UNAVAILABLE服务可能暂时超载或停机。该服务暂时耗尽容量。检查 Gemini API状态页 对于任何正在发生的事件。暂时切换到另一个型号(例如从 Gemini 2.5 Pro 到 Gemini 2.5 Flash)并查看是否有效。或者稍等一下,然后重试您的请求。如果重试后问题仍然存在,请使用 发送反馈 Google AI Studio 中的按钮。
504DEADLINE_EXCEEDED该服务无法在期限内完成处理。您的提示(或上下文)太大,无法及时处理。在客户端请求中设置更大的“超时”以避免此错误。

错误响应格式 #

当一个 GenerateContent 请求失败,API设置HTTP状态码(如 400 Bad Request, 403 Forbidden, 或 429 Too Many Requests)并返回包含 gRPC 状态详细信息的 JSON 响应正文:

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整数HTTP 状态代码。
message字符串人类可读的错误描述。
status字符串gRPC 状态代码位于 SCREAMING_CASE.
details数组其他错误上下文,例如 ErrorInfo 或 LocalizedMessage.

后续步骤 #

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