Gemini API 速率限制（2026）：按项目、用量层级与服务通道排查 429

Gemini API 没有一个适用于所有入口和账号的统一速率限制。Developer API 的实际限制由项目、模型、用量层级、指标和服务通道共同决定；Google 要求在 AI Studio 查看当前项目与模型的有效限制，而不是把公开表格当成保证值。

请求失败后，先保留 HTTP 状态码和完整错误体，再决定是否改代码或结算设置。429 RESOURCE_EXHAUSTED 属于限制被耗尽的分支，503 UNAVAILABLE 属于暂时容量不足的分支。如果耗尽的是每日请求数、滚动支出、预付余额或明确配额，盲目重试只会制造新的请求洪峰。

先确认请求进入了哪个 Google 产品

“Gemini”同时出现在消费应用、开发者 API、Firebase 和 Google Cloud 中，但四者的限制并不由同一套控制面管理。模型名称相同，也不能证明配额来源相同；应从 SDK、终端节点、项目和身份链路判断请求实际去了哪里。

这一步能解释很多看似矛盾的现象：Gemini 应用可能提示使用上限，但 Developer API 项目仍有余量；Firebase 客户端可能没有触及模型提供方配额，却被单用户网关拦截；Vertex AI 可能在 Cloud 容量层返回 429，而 AI Studio 中同模型家族看起来完全正常。

后文所说的 Developer API，特指通过 ai.google.dev 契约和 API Key 调用的 Gemini API。Firebase 与 Vertex AI 各自保留平台层限制，不能只作为“同一个 API 的不同入口”处理。

Developer API：指标、项目、模型和层级共同决定限制

Google 的速率限制文档把常见限制拆成三个核心维度，并明确说明它们按项目而不是按 API Key 聚合。

只要任一被执行的维度越界，就可能返回 429。RPM 很低并不代表输入 TPM 没有耗尽；每次输入很短，也不能证明 RPD 仍有余量。“今天只点了几次”不是有效证据，因为同一项目可能还承载生产服务、Notebook、定时任务和其他成员的 Key。

部分模型或模态还会出现 TPD（每日 token 数）、IPM（每分钟图片数）以及 Batch 专属限制。这些都应视为模型和通道拥有的当前值，而不是 Gemini 全局统一指标。图片生成的 IPM 和对应 429，应交给更窄的 Gemini 图片 429 排查页处理。

真正需要记住的是两条边界。第一，配额池属于项目；在同一项目里轮换 Key 只改变凭据，不改变容量。第二，AI Studio 才是当前项目和模型的实际数值入口。Google 明确说明公开列出的限制并不保证，实际容量可能不同；文档适合解释规则，控制台才适合决定此刻的诊断。

实验和预览模型通常更严格，免费可用性与模型定价也会独立变化。如果尚未确定模型是否属于免费路径，应查看 Gemini API 免费层指南，不要把“免费模型能调用”和“当前项目还有配额”混成一个结论。

一分钟内找到限制所有者

能够跨团队复现的证据，比“偶尔会报错”有用得多。每次失败至少记录以下信息：

• 产品入口与完整终端节点；
• 项目 ID 和 API Key 的归属，但不要记录密钥本身；
• 精确模型、服务方式和调用方法；
• HTTP 状态码、错误状态和完整消息；
• 带时区的请求时间；
• 输入规模、并发数和近期重试次数；
• 相同时间段的 AI Studio 或 Cloud 使用量视图。

然后按固定顺序判断：

1. 入口：请求来自 Gemini 应用、Developer API、Firebase AI Logic 还是 Vertex AI？
2. 状态：这是 429 限制事件，还是 503 暂时容量事件？
3. 指标：Developer API 下最可能是 RPM、输入 TPM、RPD、滚动支出、余额、Priority 或 Batch 中的哪一项？
4. 聚合范围：控制项属于哪个项目或结算账号？还有哪些工作负载共享它？
5. 服务通道：请求走 Standard、Priority、Batch、Firebase 网关，还是 Vertex 容量？
6. 控制台：所有者对应的控制台是否与同一时间的错误吻合？
7. 动作：只改一个确实能影响该所有者的变量。
8. 验证：用同一项目、模型、负载和指标确认恢复。

用量层级、滚动支出、余额和上限不是同一件事

涉及钱的 429 最容易被一句“开通结算”误导。根据 2026 年 7 月 14 日重新核对的 Google 官方速率限制与结算文档，至少要分开以下控制项：

层级资格由连接到项目的结算账号决定，请求配额则仍按 Developer API 的项目范围聚合。因此，两个项目可以因为同一结算账号而处于同一用量层级，但不会自动合并成一个请求池。反过来，调高项目支出上限也不会让已耗尽的模型 RPD 消失。

这些具体数字都属于高波动事实。上线前应重新打开 Google 官方用量层级与支出限制页面，再与项目的有效限制对照。结算历史、账号状态、付款到账和报表延迟都可能影响结果。

例如，某个 Tier 2 项目的 RPM 看起来很低，却持续收到 429。如果 10 分钟内的高成本请求触发滚动支出限制，提高并发和多建 Key 只会更快失败；如果滚动支出正常但预付余额已耗尽，等待一分钟同样无效；如果两者正常而 RPD 已耗尽，继续充值也不是正确动作。必须先给控制项命名。

扩容前先选对 Standard、Priority 或 Batch

服务通道本身就是限制合同的一部分，不是出错后随便换的标签。

Google 的 Batch API 文档给出的完成目标可长达 24 小时，并说明创建任务不是幂等操作。客户端应先生成持久任务 ID，保存 API 返回的任务名；创建请求超时后不能直接重复提交，否则可能制造重复工作和重复费用。

Batch 不是“换个地方继续重试”。它适合可以等待的离线负载，并能把交互资源留给前台；它不适合正在等待当前响应的用户，也有自己的排队和存储边界。Priority 同样不是所有项目的免费加速器，必须先确认资格和两套余量。

只有时间或流量形状能改变结果时才重试

Google 的问题排查文档把 429 RESOURCE_EXHAUSTED 与 503 UNAVAILABLE 分开。代码进入重试循环前，也必须做同样的分流。

下面的函数故意要求调用方判断 429 是否暂时可恢复。这样，通用封装就不能默认猛攻每日配额或余额耗尽这类硬边界。

javascript
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function withGeminiRetry(run, {
  maxAttempts = 5,
  baseDelayMs = 750,
  maxDelayMs = 20_000,
  isTransient429 = () => false,
  onRetry = () => {},
} = {}) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    try {
      return await run();
    } catch (error) {
      lastError = error;
      const status = Number(error?.status ?? error?.code ?? 0);
      const retryable =
        status === 500 || status === 503 || status === 504 ||
        (status === 429 && isTransient429(error));

      if (!retryable || attempt === maxAttempts) throw error;

      const ceiling = Math.min(
        maxDelayMs,
        baseDelayMs * 2 ** (attempt - 1),
      );
      const delayMs = Math.floor(Math.random() * ceiling);
      onRetry({ attempt, status, delayMs, message: error?.message });
      await sleep(delayMs);
    }
  }

  throw lastError;
}

函数外还要有按项目和模型计算的并发限制器，否则十个工作进程会同时醒来，把恢复过程变成下一次峰值。能做幂等的操作应带业务幂等键，重复输入应缓存，总重试时间不能超过用户可感知的延迟预算。

isTransient429 只有在证据说明“等待会改变限制所有者”时才返回 true，例如短时 RPM 峰值且没有触及每日硬边界。RPD 耗尽、预付余额为零、支出上限、被拒绝的配额申请，或任何需要配置变更的所有者，都应返回 false。

Firebase AI Logic 还有一层单用户网关限制

Firebase AI Logic 不会替代模型提供方配额。根据 2026 年 7 月 14 日核对的 Firebase 配额文档，提供方限制仍然生效并优先；Firebase 网关另外增加可配置的单用户速率限制，文档默认值为每用户 100 RPM。

因此会出现两种完全合理的失败：很多用户各自都低于 Firebase 单用户限制，却共同耗尽提供方项目或模型配额；也可能只有一个异常客户端触发单用户网关限制，而提供方容量仍充足。

核对同一个请求的 Firebase 层、App Check 身份和提供方用量。提高单用户阈值不会扩大提供方容量，提高提供方容量也不会取消有意设置的客户端保护。只修改产生证据的那一层。

Vertex AI 的 429 属于 Cloud 容量合同

Vertex AI 请求走 Google Cloud 终端节点、项目、位置和容量控制。Google 的 Vertex AI 429 文档区分按量付费与 Provisioned Throughput，并为两者给出不同错误消息和处理方式。

按量付费下，可能的动作包括在支持时使用 global endpoint、平滑流量、有上限地重试、为基于配额的模型申请提高限制，或改变容量方案。Provisioned Throughput 下则要确认请求是否在已购吞吐内、超出部分是否按 pay-as-you-go 处理。错误消息本身是分流证据，不能只留下状态码。

不要只看 AI Studio 诊断 Vertex 请求。第一现场是 Cloud 项目、终端节点、位置、配额视图和 Provisioned Throughput 状态。如果问题已经变成“生产系统应选择哪个平台”，再转到 Gemini API 与 Vertex AI 对比，不要在 429 现场同时重做平台选型。

按能否改变限制所有者安排容量动作

确认所有者后，动作应从最小、最可逆的变化开始：

1. 消除浪费：缓存重复请求，删除重复上下文，阻止递归重试，并取消用户已经放弃的任务。
2. 重塑流量：队列化突发，按项目和模型限制并发，为交互请求预留余量。
3. 选择合格通道：离线工作迁到 Batch；只有合同和余量匹配时才使用 Priority。
4. 改变负载形状：选择满足质量要求的轻量模型，拆分长输入，减少无用输出。
5. 修复财务控制项：恢复合格余额、调整正确的支出上限，或等待层级资格生效。
6. 获取容量：申请提高限制，或在确实需要 Cloud 管理和容量合同的场景采用合适的 Vertex 路径。
7. 诊断完成后再做多提供方设计：只有“单一提供方集中风险”已经被证据证明，才评估 fallback 架构。

如果最后一项是实际工程任务，可以把 laozhang.ai 作为多模型网关候选进行测试。它不会扩大 Google 项目配额。上线前应验证模型等价性、超时与切换策略、幂等性、数据处理、可观测性和成本；这里不承诺价格、覆盖范围、速度、在线率或可用性。

容量变更必须对应可观察指标。用同一项目、模型和代表性负载，观察原先失败的指标。部署成功并不等于配额恢复；429 率下降、延迟稳定、没有重复任务、请求与 token 利用率符合预期，才构成验证。

常见问题

在哪里查看当前 Gemini API 速率限制？

打开 AI Studio，选择完全相同的项目和模型。公开文档解释 RPM、输入 TPM、RPD、层级和服务通道，但 Google 说明列出的限制不保证。当前项目的有效限制应以控制台为准。

Gemini API 限制按 API Key 还是按项目计算？

Developer API 按项目而不是 API Key 应用限制。同一项目的多个 Key 共享配额池。只有工作负载、所有权、结算或治理确实需要隔离时，才建立独立项目，而不是把轮换 Key 包装成扩容方案。

RPD 什么时候重置？

当前 Developer API 文档规定，RPD 在太平洋时间午夜重置。等待前先确认耗尽的确实是 RPD；RPM、输入 TPM、滚动支出、余额、Firebase 与 Vertex 都有不同窗口或合同。

为什么开通结算后仍然收到 429？

因为结算只是一个分支。项目仍可能耗尽 RPM、输入 TPM、RPD、滚动支出、项目上限、结算账号上限、Priority 或模型专属限制；预付账号还可能余额不足。应逐项核对，而不是反复切换“已结算”开关。

Priority 一定会增加容量吗？

不一定。Priority 是符合条件的独立服务合同，有自己的限制，同时还会计入交互流量。迁移前同时查看 Priority 和 Standard 的有效余量，不能把 0.3× 当成所有项目的固定增益。

Batch 能绕过交互限制吗？

Batch 有独立限制，适合异步任务，但并非无限。它受并发任务、文件大小、存储和排队 token 约束，完成可能需要 24 小时。只有负载能等待并接受异步语义时才使用。

所有 429 都应该重试吗？

不应该。只有时间或流量形状能改变被耗尽的所有者时才重试。指数退避能缓解短时峰值，却不能创造 RPD、补充余额、抬高上限或授予容量。

使用量与错误不一致时，升级处理需要什么证据？

提供完整响应体、带时区的时间、项目 ID、模型、终端节点、服务通道、请求规模、近期并发，以及同一时间段的用量视图；去掉 API Key 和用户数据。其他状态码应查看 Gemini API 错误排查，不要把所有异常都归入 429。

最后只看一条规则

先给产品入口、指标、聚合范围、服务通道和修复动作命名，再改代码、结算或架构。到正确控制台核对实际所有者，只做一个能影响它的变化，再用相同负载验证。如果硬边界仍然耗尽，就停止重试：等待正确重置、降低需求、选择合格通道，或取得容量。