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 密钥是否处于活动状态、完整 项目验证,或查看帐单 Google AI Studio。参见 项目受限或不可用. |
| 404 | NOT_FOUND | 未找到请求的资源。 | 找不到您请求中引用的图像、音频或视频文件。 | 检查请求中的所有参数对于您的 API 版本是否有效。 |
| 429 | RESOURCE_EXHAUSTED | 您已超出 API 的速率限制之一(RPM、TPM、RPD、支出等)。 | 您发送了太多请求,使用了太多 token,或者超出了您帐户的账单历史记录和等级的基于支出的限制。 | 验证您是否在模型范围内 速率限制。等待一段时间后重试。降低请求的速率或大小。 请求提高速率限制 如果需要的话。 |
| 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 | 整数 | HTTP 状态代码。 |
message | 字符串 | 人类可读的错误描述。 |
status | 字符串 | gRPC 状态代码位于 SCREAMING_CASE. |
details | 数组 | 其他错误上下文,例如 ErrorInfo 或 LocalizedMessage. |