Gemini API 配额超限(429 RESOURCE_EXHAUSTED)
当您超过速率限制或每日配额时,Gemini API 会返回 429 RESOURCE_EXHAUSTED。在免费套餐中,限制很小。本页说明该错误的每种形式、当前的免费限制,以及有效的修复方法。
代码、模型名称和目录中的实时标签以英文显示。
错误的样子
Google 开发者论坛上发布的典型免费套餐错误包含以下部分:
免费套餐返回的 429 示例
429 RESOURCE_EXHAUSTED
You exceeded your current quota, please check your plan and billing details.
Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests, limit: 50
quotaId: GenerateRequestsPerDayPerProjectPerModel-FreeTier
Please retry in 11.615098148s.quotaMetric告诉您哪一项已用完。generate_content_free_tier_requests统计免费套餐的请求数。quotaId告诉您限制的时间窗口。PerDay表示每日配额。PerMinute类 ID 表示每分钟限制。limit是该模型在该时间窗口内的配额。Please retry in给出 Google 建议的等待时间。
三个 429 代码和一个 403
Google 的 API 错误页面列出了三个 HTTP 429 错误代码,以及一个相关的 403:
| 代码 | HTTP | 含义 | 解决方法 |
|---|---|---|---|
rate_limit_exceeded | 429 | 达到每分钟或每秒的请求或令牌限制 | 以指数退避方式重试 |
quota_exceeded | 429 | 每日配额已用完 | 等待重置,或申请提高配额 |
too_many_requests | 429 | 短时间内请求过多 | 以指数退避方式重试 |
permission_denied | 403 | 项目受限,或该项目无法使用免费套餐 | 关联结算账户并使用付费套餐 |
每分钟限制会在不到一分钟内清除。每日配额只会在重置时清除。Google 在太平洋时间午夜重置每日请求数。在重置之前重试每日配额错误,只会浪费请求。
当前的免费套餐限制
Google 按每个 Google Cloud 项目设置限制,而不是按每个密钥。每个模型的限制各不相同。Google 会在 AI Studio 中显示您的有效限制。下表列出 FreeLLMAPI 目录中的免费 Gemini 和 Gemma 限制。
| 模型 | 免费提供方 | 上下文 | 免费额度(最优惠) | 工具 | 视觉 |
|---|---|---|---|---|---|
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | 是 | 是 |
| Gemini Flash (latest alias) | Google AI Studio | - | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini 3.5 Flash | Google AI Studio | 1M | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini 3.8 Live | Google AI Studio | - | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini 3.8 Live Extended Thinking | Google AI Studio | - | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini 3.8 Flash TTS | Google AI Studio | - | Ongoing AI Studio free-tier quota; account limits apply | 否 | 否 |
| Gemini 3.8 Flash-Lite TTS | Google AI Studio | - | Ongoing AI Studio free-tier quota; account limits apply | 否 | 否 |
| Gemini Robotics-ER 2 Preview | Google AI Studio | 131K | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 否 | 是 |
| Gemini 3.5 Flash Lite | Google AI Studio | 1M | 15 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Gemini Flash Lite (latest alias) | Google AI Studio | - | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
显示 12 个(共 21 个匹配的免费模型)。 查看所有模型.
数据来自 FreeLLMAPI 目录(版本 2026.11.19,检查于 2026-11-19)。免费额度经常变化。该目录每天检查一次。
大多数 Flash 模型在免费套餐中每天约允许 20 次请求。Gemma 模型每天允许的请求数多得多,但上下文窗口较小。Google 表示,所列限制不作保证,实际容量可能有所不同。
有效的修复方法
- 读取
quotaId。如果其中包含PerDay,请停止请求,并等待太平洋时间午夜的重置。 - 对于每分钟限制,请以指数退避和抖动的方式重试。设置最大重试次数。
- 将简单任务转移到每日上限更高的模型,例如 Gemma 或 Flash-Lite 模型。
- 减少发送的令牌数。大型提示词会很快达到每分钟令牌数限制。
- 不要将
max_tokens设置得过小。Gemini Flash 可能会在输出上限内使用隐藏的思考令牌。
| 您尝试的方法 | 是否有效? | 原因 |
|---|---|---|
| 在同一项目中创建新的 API 密钥 | 否 | 限制作用于项目。Google 表示,新密钥无法解决该错误。 |
| 将项目升级到付费套餐 | 提供付费配额 | Google 表示,付费套餐不会提供免费套餐的配额。付费使用会产生费用。 |
等待 retry in 指定的时间 | 对每分钟限制有效 | 每分钟的时间窗口会滚动重置 |
| 更换为其他模型 | 有效 | 每个模型都有各自的配额 |
发送前检查配额
您可以在出现错误之前发现问题。在 AI Studio 中,打开 Gemini API 文档中的速率限制页面。该页面会显示您项目中每个模型的有效限制。Projects 页面显示您的套餐等级。
如果您使用 FreeLLMAPI,可以向网关查询哪些模型现在可用。状态为 exhausted 的模型,其所有密钥都处于冷却状态。冷却时间结束后,该状态会自动清除。
列出当前可以响应的模型
curl "http://localhost:3001/v1/models?execution_status=ready" \
-H "Authorization: Bearer <unified-key>"用简单的数字规划每日使用量。如果每天 20 次请求,一个 Flash 模型在一整天内大约每 72 分钟才能发送一次请求。一个编码代理完成一项任务就可能用掉 20 次请求。请只将 Flash 模型用于困难任务,并将简单任务发送给每日上限更高的模型。
切换到其他免费提供方
每天约 20 次 Flash 请求,单个 Gemini 密钥不足以支撑代理工作。FreeLLMAPI 将 Gemini 与其他免费提供方一起放在一个端点之后。当 Gemini 返回 429 时,路由器会将请求发送到您链中的下一个模型。
- 路由器会为每个模型和密钥统计 RPM、RPD、TPM 和 TPD。它会在达到已知限制之前停止。
- 短时间的 429 会使该密钥进入 90 秒冷却。每日配额用完时,冷却时间更长:依次为 2 分钟、10 分钟、1 小时,然后是 24 小时。
- 如果 Google 给出的重试时间更长,路由器会采用 Google 的数值。
X-Fallback-Trail标头列出每一次失败的跳转,例如google/gemini-2.5-flash key1=rate_limited。
通过网关发送 Gemini 流量
curl -fsSL https://freellmapi.co/install.sh | bash
curl -i http://localhost:3001/v1/chat/completions \
-H "Authorization: Bearer <unified-key>" \
-H "Content-Type: application/json" \
-d '{"model": "auto", "messages": [{"role": "user", "content": "hi"}]}'Gemini CLI 也可以使用网关的原生 /v1beta 接口。网关不会增加 Gemini 配额。当 Gemini 达到限制时,它会使用其他提供方。
已知的 Gemini 特殊情况
| 提供方 | 已知问题 | 处理方法 |
|---|---|---|
| Google AI Studio | Thinking tokens use output cap | Gemini Flash can spend hidden thinking tokens inside maxOutputTokens. Avoid tiny max_tokens values or set thinkingBudget to 0 when provider support is available. |
数据来自 FreeLLMAPI 目录(版本 2026.11.19,检查于 2026-11-19)。免费额度经常变化。该目录每天检查一次。
常见问题
Gemini API 中的 429 RESOURCE_EXHAUSTED 是什么意思?
这表示您的项目超过了速率限制或配额。错误正文中的 quotaId 会告诉您它是每分钟限制还是每日配额。
Gemini 免费套餐的配额何时重置?
每日请求数在太平洋时间午夜重置。每分钟限制会在一分钟内重置。
为什么新的 Gemini API 密钥无法解决配额错误?
Google 对 Google Cloud 项目设置限制,而不是对密钥。同一项目中的每个密钥共享同一配额。
Gemini 配额错误中的 limit: 0 是什么意思?
这表示您的项目在该时间窗口内对该模型没有免费配额。部分项目不符合免费套餐的条件。请在 AI Studio 中查看您的限制,或尝试其他模型。
如何在编码代理中避免 Gemini 429 错误?
在一个网关之后使用多个免费提供方。当 Gemini 达到限制时,网关会将请求发送到另一个提供方,因此代理可以继续工作。
相关指南
来源
- Google AI Studio: Rate limits (检查于 20 November 2026)
- Google AI Studio: API errors (检查于 20 November 2026)
- Google AI Studio: Troubleshooting (检查于 20 November 2026)
- Google developer forum: free tier quota error example (检查于 20 November 2026)
- FreeLLMAPI docs: Quota and cooldown engine (检查于 20 November 2026)
- FreeLLMAPI docs: Response headers (检查于 20 November 2026)