本文要点
- 429 不只表示请求太快：先从错误正文确认是 RPM、TPM、RPD，还是容量临时不足。
- Gemini 配额按 Google Cloud project 计算，不按单个 API key 计算；新建同项目密钥通常不会获得新配额。
- 只对 408、429 和 5xx 等暂时性错误做有限次数的指数退避，并加入随机抖动；400、403 不应盲目重试。
- RPD 按美国太平洋时间午夜重置，排查时要保留时区、模型、project、状态码和 request ID。
- 出现密钥泄露提示时应立即撤销并轮换，不要把真实密钥放进浏览器、仓库、截图或工单。
先判断：这是配额、容量、权限还是网络
Gemini API 返回错误后，先保存 HTTP 状态码、JSON 错误正文、模型名、请求时间、Google Cloud project 和 request ID。429 通常与配额或服务容量有关；503 多为服务暂时不可用或容量不足；403 更应检查密钥、项目、区域和权限；DNS、连接超时、TLS 或代理认证失败才属于网络层。
不要只看一句“调用失败”就换代理或换密钥。先用一个不含敏感数据的最小请求复现，再对照 <a href="/resources/ai-api-key-base-url-model-guide">API Key、Base URL 与 Model 配置指南</a>确认请求入口和模型标识。
RPM、TPM、RPD 分别限制什么
RPM 是每分钟请求数，TPM 是每分钟输入 token 数，RPD 是每天请求数。任一维度先耗尽都可能触发限制，因此低请求数不等于没有超过 TPM；长上下文和批量并发尤其容易先碰到 token 维度。
官方说明配额按 project，而不是按 API key 计算。把同一 project 下的请求拆到多个 key 不能增加总配额。RPD 按美国太平洋时间午夜重置，跨时区团队应在监控和工单中同时记录本地时间与该重置口径。
哪些错误可以重试
对 408、429 和 5xx，可在确认请求幂等或可安全重放后使用指数退避：例如等待约 1 秒、2 秒、4 秒、8 秒，并加入随机抖动，设置最大次数与总等待上限。若响应含 Retry-After，应优先遵守服务端提示。
400 通常是参数或请求体问题，403 通常是权限、密钥或政策边界；原样重试不会修复它们。持续 429 也不应无限重试，应降低并发、缩短输入、排队或申请更高配额，避免重试风暴扩大费用和故障。
429 与 503 的最小排查流程
第一步查看错误正文和配额控制台，确认触发维度；第二步把并发降到 1，用短输入和同一模型做最小请求；第三步观察有限退避后是否恢复；第四步比较另一个已获准模型或非高峰时段，但不要用换账号规避限制；第五步记录结果后再调整队列、缓存和并发。
如果所有模型都在建立连接前失败，或出现 DNS、TLS、407、连接超时，应转到 <a href="/resources/proxy-connection-troubleshooting-checklist">代理连接失败排查清单</a>。网络出口可以改善连通性，但不能增加 Gemini project 配额或解除密钥封禁。
密钥泄露提示怎么处理
若错误明确提示 API key 被报告泄露，应停止使用该 key，在 Google Cloud 控制台撤销或删除，创建受限制的新 key，并检查仓库历史、前端包、CI 日志、截图和工单是否暴露。仅重试或更换网络出口不能恢复被封禁的密钥。
新 key 只放在服务端秘密管理或受控环境变量中，限制可调用的 API、来源和权限。轮换后先用最小请求验证，再恢复流量；同时清除日志中的完整 Authorization、key 和用户数据。
上线前检查表
至少检查：按 project 监控 RPM/TPM/RPD；为不同模型设置独立队列；重试有次数、总时长和抖动上限；400/403 直接进入人工或配置排查；日志保留状态码、错误码、request ID 和模型但不留密钥；成本与失败率有告警；降级路径不会重复计费或重复执行副作用。
团队需要稳定访问海外 API 文档和控制台时，可以 <a href="/" target="_blank" rel="noopener noreferrer">访问 PuppyIP 官网</a>了解固定网络出口。它只解决连接路径问题，不承诺提升官方配额、模型可用性或账号权限。
资料来源
常见问题
Gemini API 429 一定是每分钟请求太多吗？
不一定。RPM、TPM、RPD 或服务容量都可能相关，应以错误正文和项目配额页面为准。
同一个 project 多建几个 API key 能增加配额吗？
不能据此增加。官方说明配额按 project 计算，而不是按单个 API key 计算。
Gemini 503 可以一直重试吗？
不应无限重试。只做有限次数、带抖动的指数退避，并设置总等待上限；持续失败应降载或停止。
为什么 403 不建议自动重试？
403 通常指向权限、密钥、项目或政策边界，原样重试不会改变这些条件。
RPD 什么时候重置？
Gemini 官方说明每天请求配额按美国太平洋时间午夜重置，跨时区排查要记录准确时间。
代理能解决 Gemini 429 吗？
代理只能影响网络路径，不能增加 project 配额。只有错误证据指向 DNS、连接、TLS 或代理认证时才应排查网络。