Gemini 的两种 429 完全不是一回事：退避重试救不了哪一种

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

很多人写 Gemini 客户端时，把 429 当成一个错误来处理：捕获、退避、重试，最多加个上限。但官方错误参考里，429 这个 HTTP 状态码下面挂着两个语义完全不同的错误码——rate_limit_exceeded 是分钟级/秒级的速率超限，官方给的处置就是等待加指数退避；quota_exceeded 是每日配额耗尽，官方给的处置是等配额重置或者申请提额。后者你退避一百次也没用，只会把重试预算烧光、把日志刷满，然后在第二天配额重置的那一刻突然”自愈”，留下一段谁也看不懂的故障曲线。分辨它们不能看 HTTP 状态码，只能看响应 error 对象里的 code 字段。更麻烦的是流式请求：官方文档写明流式的错误是通过 SSE 事件传的，不设 HTTP 状态码，只判状态码的客户端连这两个 429 都收不到。

先搞清楚：429 是状态码，不是错误码

Gemini API 的错误响应统一返回一个 error 对象，里面有两个字段：code 是机器可读的 snake_case 字符串，message 是给人看的说明。官方错误参考页把错误分成三族，其中”标准请求级错误码”那一族才和 HTTP 状态码有对应关系，比如 authentication 对 401、permission_denied 对 403、not_found 和 model_not_found 都对 404。

注意最后那对：两个不同的 code 共用一个 HTTP 状态码。429 也是同样的情况，官方表格里 429 那一行不止一条，rate_limit_exceeded 和 quota_exceeded 并列，含义与推荐处置各写各的。

所以那句老生常谈——“按状态码分支处理”——在 Gemini 这里是不够的。你的分流逻辑必须下沉一层，读 error.code。官方还补了一句：没有在表里列出的错误码，API 会以标准 HTTP 状态文本的 snake_case 形式返回，所以你的 default 分支不能崩，得能接住没见过的字符串。

rate_limit_exceeded：分钟级超速，退避重试确实有用

官方对 rate_limit_exceeded 的定义是：超出了每分钟或每秒的请求数或 token 数限制。推荐处置写得很直接——等待后用指数退避重试。这是唯一一个”教科书式退避真的能救”的 429。

想理解它什么时候触发，得看限流文档里那几个维度。官方列出的基本维度是 RPM（每分钟请求数）、TPM（每分钟输入 token 数）、RPD（每日请求数）。关键的一句是：超出其中任何一个维度就会触发限流错误，不是把三个维度综合评估之后再决定。很多人以为自己请求数远没到上限就不会被限，结果是长上下文请求把 TPM 打满了——请求数确实不多，但每个请求的输入 token 太大。

除了这三个基本维度，官方还提到部分模型有额外维度：IPM（每分钟图片数）只对能生成图片的模型计，部分模型另有 TPD（每日 token 数）。做图片类工作负载时，你排查的对象和纯文本场景不是同一个计数器。

这里有一个最常见的误解值得单独说：限流是按项目（project）应用的，不是按 API 密钥应用的。官方文档写明 API 密钥没有独立的结算设置，它继承所属项目的层级与结算状态，同一个项目里所有密钥的用量合并计入。所以”多申请几个 key 分摊流量”这条路在 Gemini 上是走不通的，多个 key 打的是同一个池子。这一点值得单独展开，可以看限流到底按什么维度算里的通用口径对照。

quota_exceeded：每日配额耗尽，退避多少次都是白烧

官方对 quota_exceeded 的定义是超出每日配额，推荐处置是等待配额重置，或者申请增加配额。注意这两条处置里没有”重试”这个词。

这就是本文标题那句话的落点。指数退避的假设是”资源在短时间内会重新可用”，对分钟级窗口成立，对日级配额不成立。你的退避算法哪怕退到几十分钟一次，也改变不了当天配额已经归零这个事实；它唯一的效果是把失败请求持续送到服务端，同时让你的告警系统一直报警到午夜。

说到午夜，这里有个非常容易踩的细节：RPD 配额在太平洋时间午夜重置，既不是你的本地时间，也不是 UTC。国内团队按北京时间去推算”什么时候能恢复”，算出来的时点必然是错的。做熔断恢复调度、写值班文档、给业务方承诺恢复时间，都要按太平洋时间那个分界去换算。

另外官方特别提到：实验性模型与预览版模型的限流更严格。如果你在预览型号上撞到 quota_exceeded 的频率明显高于正式型号，那不是你的用量突然涨了，是这类模型本来就配得更紧。把关键链路挂在预览型号上，就要接受这份代价。

还有第三种 429：基于支出的速率限制

除了 RPM/TPM/RPD 这一层，官方限流文档还写了另外一层——基于支出的速率限制。它按一个滚动时间窗口评估（官方文档写的是十分钟滚动窗口，具体以官方文档当前版本为准），是否适用于你，取决于你的结算记录与账号状态。触发时返回的是 429 RESOURCE_EXHAUSTED。

它棘手的地方在于：从状态码上看还是 429，但触发原因既不是你请求发得太快，也不是当天次数用完了，而是这个窗口里累计消耗的费用太高。所以你去看 QPS 曲线会发现一切正常，去看当天请求总数也没到头，排查会卡住。

官方给的处置有三条，第一条是等待后重试，第二条很值得单独抄下来——降低高费用请求的速率，具体做法是用更小的上下文窗口或者更短的输出。这条处置在整个错误体系里是独一份的：它要你改的不是重试策略，而是单次请求的形状。第三条是持续触发就去申请提高限流。

顺带说一句为什么”更短的输出”能救：Gemini 定价页表头明文写着输出价格包括思考 token。开了推理的模型，思考部分是算进输出的，你看到的可见文本长度并不代表这次调用真实的输出量。要压支出侧的速率，就得连思考预算一起压。

客户端该怎么分流：三条分支，别写成一条

把上面三种情况拼起来，一个能用的 429 处理逻辑至少要分三支：

• code == "rate_limit_exceeded"：正常走指数退避重试，这是它设计出来就是要应付的场景。同时把触发时刻的输入 token 量记下来，方便回头判断是撞了 RPM 还是撞了 TPM。
• code == "quota_exceeded"：立刻熔断，不要重试。把恢复时点按太平洋时间午夜去算，或者切到走另一个项目的配额，或者去申请提额。在熔断期内直接给上游返回明确的”今日配额耗尽”，比让请求排队几小时后超时要诚实得多。
• 支出侧限流（RESOURCE_EXHAUSTED）：退避之外还要降级请求形状——裁剪上下文、限制输出长度、必要时降低推理档位。只退避不改形状，下一个窗口大概率还会再撞一次。

流式请求要额外加一层。官方错误文档写明：标准（非流式）请求出错时会设置 HTTP 状态码，同时在 JSON body 里返回 error 对象；而流式请求（SSE，stream: true）出错时，是通过 SSE 流发送 event_type: "error" 的事件，error 字段结构相同。直接后果是——只判 HTTP 状态码的客户端会完全漏掉流式过程中的错误，表现出来就是”流莫名其妙断了但没报错”。所以流式路径上必须解析事件类型，把拿到的 error.code 送进上面同一套分流逻辑，不能两套代码各写各的。

排查时几个容易搞混的边界

• Batch API 的限流完全独立于非批量调用。官方另外列了并发作业数、输入文件大小、文件存储总量、每模型排队 token 数四类约束。所以在线接口被限流，不代表你的批量任务也会被限；反过来也一样，别拿在线接口的曲线去解释批量任务的失败。
• 优先级推理有自己的限流，官方给出的是相对标准限流的一个固定关系（具体倍率见官方文档）。换服务档位等于换了一套限流，不要沿用旧档位的经验阈值。
• 层级、限流、账号上限都在结算账号级别确定，不是项目级别。项目从一个结算账号换到另一个，层级与限流会随新结算账号变化；解除项目与结算账号的关联，会退回免费层。所以”我明明什么都没改，限流怎么变严了”这类现象，第一个要查的是结算关系有没有被动过。
• 官方在限流页写了一句免责原话：指定的速率限制无法保证，实际容量可能有所变化。把限流数值硬编码进代码里当作恒定契约，本身就是个隐患，机制可以固化，数值不该固化。

最后：先把 code 记进日志

这件事上最容易栽的坑不是处置策略写错，而是日志里根本没记 error.code。只记了 HTTP 状态码和一段 message 文本，事后就没办法区分那一波 429 到底是分钟级超速还是当日配额打满，也就没办法判断当时的重试是有效的还是纯粹在空转。

所以第一步不是去改重试算法，是先把 error.code 和触发时刻的输入 token 量一起落进日志和监控指标。有了这两个字段，前面所有分支才有判断依据。配套的成本与用量观测怎么搭，可以参考API 成本监控怎么做；如果你现有的 429 处理还停留在”统一退避”的通用写法，通用的 429 处理套路那篇讲的是跨厂商共性，本文讲的则是 Gemini 在这个共性之下多出来的那一层区分。

本文所有错误码与处置说明均来自 Gemini 官方错误参考文档，以官方文档当前版本为准。官方未说明的部分——比如 quota_exceeded 触发后申请提额的具体审核口径、支出侧限流适用与否的具体判定规则——官方文档里没有找到相关说明，不要凭其他厂商的经验去补。