Gemini API 429 RESOURCE_EXHAUSTED：先读对限制，再修复限额错误

Gemini API 429 RESOURCE_EXHAUSTED 的意思不是“代码一定坏了”，而是当前请求撞到了某个限制边界。真正有用的修复顺序，是先判断挡住请求的是 AI Studio 里当前 project 的实时限制、多个 workload 共用的 project 配额池、billing / prepay 状态、突发请求形状，还是 Vertex AI 那套不同的容量合同。

Google 当前 troubleshooting 文档把 HTTP 429 对应到 RESOURCE_EXHAUSTED，含义是超过 rate limit。rate-limits 文档进一步说明，限制通常按 RPM、input TPM、RPD 等维度计量，按 project 而不是 API key 生效，并且实际 active limits 要去 AI Studio 查看，因为公开列出的限制并不保证等于当前容量。截至 2026-05-03，这就是当前可采用的事实边界。

先按这个顺序排查：

新鲜度说明：Gemini API rate limits、troubleshooting、billing、pricing、Vertex AI 429 行为，以及 Google Cloud 的 429 resource exhaustion 建议，均在 2026-05-03 重新核对。

先把 429 当成限制分支，而不是泛泛的宕机

第一分钟要做的是分支判断。如果 response body 写着 RESOURCE_EXHAUSTED，在没有反证之前先留在 limit 分支。503 UNAVAILABLE 更像临时容量不足；400 FAILED_PRECONDITION 可能是免费层在调用地区不可用，需要启用 billing；429 则说明当前路线认可了请求格式，但因为某个限制边界拒绝服务。

最常见的误判，是把所有 429 都当成代码 bug。Backoff wrapper 对突发流量和短暂容量紧张有用，但如果 project 已经用完 RPD、另一个 worker 正在吃同一份 quota、prepay 余额为零，或者选择的模型本来就不是免费 API 路线，retry 只会把问题拖得更久。

日志必须保留完整错误体。对于 JavaScript 的 @google/genai，Google SDK 文档展示了 API error 对象可读 name、message、status 等字段。至少要把这些字段、model、project、endpoint 和时间窗写进日志，后面才有资格做 same-path 验证或找支持。

查 AI Studio，不要背一张旧 quota 表

公开 tier 表能解释账号大概处在哪个容量层级，但不能证明此刻这个 project 的 live serving limit。Google 的 rate-limits 文档已经把 active rate limits 指向 AI Studio，所以排查习惯要从“我记得某个模型有多少 RPM”改成“同一 project、同一 model 现在到底是哪条 metric 变红”。

在 AI Studio 里先回答三个问题：

1. 被打满的是 RPM、TPM、RPD、IPM，还是 batch-specific limit？
2. 触发错误的是哪个 model、哪个 route、哪个 project？
3. dashboard 与报错是否吻合，还是出现“看起来没用满但仍然 429”的异常？

如果 dashboard 已经显示饱和，下一步就是容量或流量形状；如果 dashboard 与错误不吻合，就收集 request time、model、project、response body 和 usage view 后再升级处理。不要本能地多建 API key。Gemini API 的限制按 project 生效，同一个 project 里的多个 key 仍然共用一池。

分开 project quota、billing 和 route eligibility

很多 429 排查会把三件事混在一起。

Project quota 是池子。生产、staging、本地脚本、batch worker 只要使用同一个 Google Cloud project 下的 key，就可能互相抢 quota。多建 key 不会制造新容量。只有当 workload 的所有权、计费、监控和权限边界都合理时，拆 project 才是正确动作。

Billing 是账号状态。Google 当前 billing 文档说明，paid tier status 是动态的，新用户可能使用 Prepay；当 billing account 的 prepay credit balance 变成 $0 时，所有关联 project 的 API key 会同时停止工作。因此“以前开过 billing”不是诊断结论。要看 billing tier column、available credits，以及 AI Studio 里是否有 Set up billing、Set up prepay、No available credits 之类的动作提示。

Route eligibility 是模型合同。有些 Gemini route 在 pricing 页仍列出 free API，有些则是 paid-only。若你选的 route 本来就不是 free-capable，再怎么优化 free tier 也不会稳定。要么换适合的模型路线，要么有意识地完成 paid setup。

只有知道限制 owner 后，retry 才有价值

Backoff 是压力管理工具，不是凭空制造容量的工具。当同一 project 和 model 能服务请求，只是请求来得太密、上下文太大或 retry 太集中时，它才是正确解法。

javascript
import { GoogleGenAI } from "@google/genai";

const retryable = new Set([429, 500, 503, 504]);

export async function callGeminiWithBackoff(run, {
  maxRetries = 5,
  baseDelayMs = 1000,
  maxDelayMs = 30000,
} = {}) {
  let lastError;

  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
    try {
      return await run();
    } catch (error) {
      lastError = error;
      const status = Number(error?.status || error?.code || 0);
      if (!retryable.has(status) || attempt === maxRetries) throw error;

      const jitterMs = Math.floor(Math.random() * 500);
      const delayMs = Math.min(baseDelayMs * 2 ** attempt + jitterMs, maxDelayMs);
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }
  }

  throw lastError;
}

这个 wrapper 外面还要加并发上限。十个 worker 同时失败、同时 retry，retry 层就会变成新的流量尖峰。Batch 任务要排队并 checkpoint；交互式产品要缓存重复 prompt，让 retry 幂等，并把短等待状态展示给用户，而不是在后台悄悄制造 retry storm。

Developer API 与 Vertex AI 的 429 合同不同

RESOURCE_EXHAUSTED 这个词会同时出现在 Gemini Developer API 和 Google Cloud / Vertex AI 材料中，但修复路径不能混用。

Gemini Developer API 先看 AI Studio：API key、project、usage tier、active limits、billing plan、prepay credits。Vertex AI 先看 Google Cloud project、endpoint、region 或 global endpoint、quota framework，以及是否购买 Provisioned Throughput。Google 的 Vertex AI 429 文档给 pay-as-you-go 的处理方向是：可用时使用 global endpoint，采用 truncated exponential backoff，对 quota-based model 提交 QIR，对 standard pay-as-you-go 做流量平滑，或用 Provisioned Throughput 获取更稳定的 service level。

这个边界能避免大量误操作。如果请求走 Vertex AI，只看 AI Studio 的 Developer API limit view 不够；如果请求来自 ai.google.dev 的 API key，把 Vertex AI Provisioned Throughput 当成第一修复动作也可能走错。

什么时候应该买更多容量

当 route、project、billing 和 traffic shape 都确认之后，容量决策就很直接。

质量允许时，先换轻量模型。gemini-2.5-flash 或 gemini-2.5-flash-lite 对高吞吐任务通常比更重的 reasoning route 更合适。离线任务可以用 Batch API。付费 workload 的 live limit 确实太低时，走 rate-limit increase。需要 Google Cloud 治理、endpoint / region 控制、QIR、Provisioned Throughput 或更正式的生产合同，再考虑 Vertex AI。

如果单一 provider 的 429 已经变成可用性风险，多 provider gateway 也可以是架构选择。像 laozhang.ai 这样的统一网关，适合需要多模型路由和 fallback 的团队；如果问题只是本地 retry 没有 backoff，就不应该把网关当成遮羞布。

常见问题

每个 Gemini API key 都有独立 429 限制吗？

没有。Gemini API rate-limit 文档明确说明限制按 project 生效，不按 API key 生效。同一 project 里的多个 key 仍然共用一个 quota pool。

启用 billing 一定能修复 RESOURCE_EXHAUSTED 吗？

不一定。Billing 可能改变 tier 和 route eligibility，但它不会修复共用 project、prepay 余额耗尽、RPD 用完或突发请求模式。

429 应该永远 retry 吗？

不应该。只有知道限制 owner 之后 retry 才有意义。临时压力和突发流量适合 retry；daily quota、billing 状态、paid-only route 不会因为 retry 变好。

当前 Gemini API 的限制数字在哪里看？

去 AI Studio 看同一 project 和 model 的 active rate-limit view。公开文档解释机制和 tier ladder，但 Google 也提醒 specified limits 不保证等于实际容量。

什么时候切 Vertex AI？

当你需要 Google Cloud project 治理、endpoint / region 控制、quota increase workflow、Provisioned Throughput 或 Vertex-owned 生产路线时再切。不要因为少写了 backoff 就把问题迁移到 Vertex AI。

实用规则

把 429 RESOURCE_EXHAUSTED 先当成 routing problem。确认同一个错误体、同一个 project、同一个 model、同一个 endpoint、同一个时间窗。确认之后再选最窄的修复：billing action、project isolation、traffic smoothing、model change、quota increase、Vertex capacity 或 gateway fallback。