Gemini API 429 怎么排查?配额、重试与 Key
429 不等于“额度用完了”。它可能是 RPM 超限、TPM 超限、每日额度、滚动 10 分钟消费上限,或者项目配额被错误地设成 0。先读错误体里的 quotaMetric,再决定是重试、降速、换项目还是切付费层;盲目加指数退避只会把失败拖得更久。

快速结论
这篇指南的直接答案是什么?
Gemini API 的 429 RESOURCE_EXHAUSTED 是限流/资源耗尽:可能是 RPM/TPM/RPD、滚动 10 分钟消费上限,或项目配额异常。免费层不适用消费上限,Tier 1 约每 10 分钟 10 美元,Tier 2/3 约 200 美元。429/408/5xx 可以指数退避重试,400/402/403 不要重试;403 多半是项目、账单、验证或 Key 泄露问题。先确认实际项目、配额维度和模型,再调整请求或申请提额。
购买前先记住这几点
- 429 可能是速率、每日额度、消费上限或项目配额问题。
- 限制按项目计算,不按 API Key 拆分。
- Tier 1 滚动 10 分钟消费上限约 10 美元。
- 429/408/5xx 可重试,400/402/403 不可重试。
- 403 常见于账单、项目验证或 Key 泄露。
直达入口:Google AI Pro 专区 · 帮助中心
429 到底代表什么?
429 RESOURCE_EXHAUSTED 表示请求被限流或资源耗尽,可能是 RPM、TPM、RPD、消费上限或项目配额,不一定是“额度用完”。
Gemini API 对每个维度独立检查,超过任意一个都会返回 429。错误体里通常带有 quotaMetric/quotaId,先看是哪个配额被触发,不要把所有 429 都当成同一种问题。
429 是瞬时的,但“瞬时”不等于“等一秒就好”。如果触发的是每日额度或消费上限,重试不会恢复,只会继续失败。
- RPM:每分钟请求数。
- TPM:每分钟 token 数。
- RPD:每日请求数。
- 消费上限:滚动 10 分钟。
- 项目配额异常:显示为 0 或被错误限制。
速率和消费上限怎么算?
请求/token 配额按项目计算,日额度在太平洋时间午夜重置;消费上限按滚动 10 分钟计算,Free 不适用,Tier 1 约 10 美元,Tier 2/3 约 200 美元。
消费上限和请求配额是两套限制。即使 RPM/TPM 没超,短时间大量高 token 请求也可能触发消费上限,返回 429。
免费层的消费上限为 N/A,但请求/ token 配额仍然存在,而且不同模型不同。免费层遇到 429,优先看 RPM/TPM/RPD,而不是消费上限。
| 层级 | 消费上限 | 账单上限 |
|---|---|---|
| Free | N/A | N/A |
| Tier 1 | $10 | $250 |
| Tier 2 | $200 | $2,000 |
| Tier 3 | $200 | $20,000+ |
怎么判断是项目还是 Key 的问题?
限制按项目计算,不按 Key 拆分;先确认运行时的 Key 属于哪个项目,再看该项目配额,而不是新建 Key。
同一个项目下新建 Key 不会增加额度。免费层限制也不会因为换 Key 而消失;官方明确说明,在同一项目创建新 Key 不能解决免费层限制。
如果错误是 403 而不是 429,问题通常在账单、项目验证、权限或 Key 泄露,不是限流。models.list 返回 200 只能证明 Key 存在,不能证明推理调用已开通。
- 确认运行时 Key 的项目归属。
- 在 Cloud Console 查该项目配额。
- 不要用新建 Key 规避项目限制。
- 403 查账单、验证、权限与泄露。
- models.list 不是推理权限检查。
正确的重试策略是什么?
只对 429/408/5xx 做指数退避,加 jitter、设最大次数和超时;400/402/403 直接排查,不要重试。
Python SDK 默认会对瞬时错误重试最多 4 次,初始延迟约 1 秒,最大 60 秒。自己写 REST 调用时,也要实现类似的指数退避,避免固定间隔重试造成同步打满。
重试前先缩小请求:减少上下文、降低输出上限、换更轻的模型或分批提交。对持续 429,重试只是延迟失败,应该调整配额或架构。
- 1识别状态码:429/408/5xx 才重试。
- 2指数退避,初始约 1 秒。
- 3加入随机 jitter。
- 4设置最大重试次数与总超时。
- 5缩小上下文或输出上限。
- 6持续失败就查配额或申请提额。
配额显示正常为什么还 429?
可能是滚动消费上限、模型单独配额、项目配额为 0、配额变更尚未生效,或运行时 Key 指向了另一个项目。
图像模型、批处理、文件上传等可能有独立配额,不能只看文本模型的 RPM。配额变更后也可能需要一段时间生效,短时间内仍会按旧值限流。
如果所有配额看起来都正常,检查错误体中的 quotaMetric 和请求实际使用的项目;多环境、多 Key 的项目很容易把测试和生产混在一起。
- 检查模型单独配额。
- 检查滚动消费上限。
- 确认配额变更多久生效。
- 确认运行时项目与 Key。
- 检查图像/批处理/上传配额。
什么时候该申请提额或切付费?
持续触顶、生产流量稳定、需要更高 RPM/TPM 或可预测账单时,申请提额或切付费层;偶发峰值先用退避和削峰。
提额需要说明项目、模型、当前配额、目标请求量和业务场景。只写“给我提额”通常会被退回。切付费层前先做成本估算和预算告警,避免账单失控。
如果是免费层限制,切付费层是最直接的解决方式;如果已经是付费层仍持续 429,优先查配额是否为 0 或消费上限是否过低。
- 1统计当前 RPM/TPM/RPD 峰值。
- 2确认触发的 quotaMetric。
- 3评估切付费或提额的成本。
- 4提交项目、模型、目标量说明。
- 5设置预算告警与配额监控。
- 6灰度扩容,观察 429 是否消失。
实时商品
查看当前价格、库存与交付方式
文章不写死站内价格。进入商品页可查看实时售卖状态;显示暂时缺货时无法下单。
查看全部商品价格与套餐:Gemini Pro 价格:开通包与成品号
相关专区与价格
以下页面的价格、库存与售卖状态都实时读取商品数据,可作为本文的购买与核对入口。
资料来源与复核范围
套餐和功能会变化。以下官方资料已在页面最后更新时间复核;购买前仍应打开来源查看当前版本。
- 1. Gemini API|故障排查 ↗
核对 429/403/400/503 的区别、重试策略与 API Key 问题。
- 2. Gemini API|速率限制 ↗
核对 RPM/TPM/RPD、spend-based limits、按项目计数与重置时间。
- 3. Gemini API|价格 ↗
核对 2.5、3.8 Flash、3.5 Flash-Lite 的输入输出价格与免费层。
- 4. Gemini API|API Key ↗
核对 Key 的创建、auth key、项目归属与安全限制。
常见问题
429 是额度用完了吗?
不一定。可能是 RPM/TPM/RPD、滚动消费上限或项目配额异常;先看错误体的 quotaMetric。
多建几个 API Key 能解决 429 吗?
不能。限制按项目计算,同一项目下多个 Key 共享额度。
哪些状态码可以重试?
429、408 和 5xx 可以指数退避重试;400、402、403 不要重试。
403 和 429 有什么区别?
403 通常是账单、项目验证、权限或 Key 泄露问题;429 是限流或资源耗尽。
配额显示正常为什么还 429?
可能是消费上限、模型单独配额、配额变更未生效,或运行时 Key 指向了另一个项目。