作者注：遇到 429 不必马上换模型。本文用 3 步排查判断限流来自上游厂商、网关还是免费档，并给出指数退避、Retry-After 与故障切换的配置方法。
凌晨跑批任务时日志突然刷出一屏 429 Too Many Requests，很多人的第一反应是“这个模型不行，赶紧换一个”。这个判断往往下得太早。429 只说明“有人限制了你”，没有说明是谁限制的，也没有说明限制的维度是什么。本文的核心观点是 先定位限流来源，再决定退避还是切换。
这不是一篇泛泛而谈的重试科普。我们会按照真实排查顺序，拆解错误信息、响应头和限流维度，再给出退避参数与故障切换链路的配置建议。
核心价值：读完本文，你能在几分钟内判断一次 429 来自上游厂商、中间网关还是免费档配额，并为自己的应用配好一套“该等就等、该切就切”的容错策略。
429 限流判断核心要点
429 是 HTTP 标准里的“请求过多”状态码。在大模型 API 场景中，它可能由调用链上任意一层返回。下表总结了最常见的三类来源，以及每一类对应的正确处理方式。
| 限流来源 | 典型特征 | 是否该换模型 | 推荐处理 |
|---|---|---|---|
| 上游模型厂商 | 错误体带厂商自己的错误类型与措辞，响应头带厂商限流字段 | 通常不需要 | 按 Retry-After 退避，必要时降低并发或申请提额 |
| 中间网关/聚合平台 | 错误措辞来自网关，提示账户级或分组级速率 | 不需要 | 检查网关侧配额与并发设置，或切换网关分组 |
| 免费档/试用额度 | 提示免费额度、每日次数或容量不足 | 视情况 | 升级付费档，或切换到有容量的同类模型 |
为什么 429 不等于模型挂了
模型本身不可用时，更常见的信号是 5xx 系列错误。例如 Anthropic 的过载会返回 529 overloaded_error，网关或负载均衡异常常见 502、503。这些状态码说明服务端暂时处理不过来，和“你的账号超过了配额”是两回事。
429 则带有明确的归属含义：限流规则针对的是你，可能是你的 API Key、你的组织、你所在的免费档，或者网关给你分配的速率。换一个模型有时能绕过去，但如果限流来自网关账户级配额，换模型照样会撞墙。如果限流来自上游厂商的每分钟 token 上限，等几秒就能恢复，换模型反而引入了输出质量的不确定性。
第三方对 Claude Code 的排障整理也印证了这一点：Claude Code 遇到 429 时会显示 Request rejected (429)，后面附上服务端原话，而正是这段原话告诉你限流来自 Anthropic、来自网关，还是来自免费档。所以排查的第一步永远是读完整的错误信息，而不是只看状态码。
429 与相邻状态码的区别
为了避免把不同错误混为一谈，下表列出了在大模型调用中容易与 429 混淆的几个状态码。
| 状态码 | 含义 | 责任方 | 是否适合重试 | 是否适合故障切换 |
|---|---|---|---|---|
| 429 | 请求过多，触发速率或配额限制 | 调用方额度 | 适合，需退避 | 退避无效后再切 |
| 529 | 上游过载（Anthropic 特有） | 服务端容量 | 适合，短暂退避 | 适合 |
| 503 | 服务暂不可用 | 服务端或网关 | 适合 | 适合 |
| 500/502 | 内部错误或网关错误 | 服务端或网关 | 有限次重试 | 适合 |
| 400/401/403 | 参数、鉴权或权限问题 | 调用方配置 | 不适合 | 不适合，需修配置 |
这张表里有一个容易被忽略的细节：Claude Code 的 fallbackModel 机制据第三方测试只在 529 过载时触发，最多尝试 3 个备用模型，而不是在 429 时触发。这说明工具设计者本身也认为，429 的第一反应应该是退避，而非换模型。
如何判断 429 限流来自谁：3 步排查
下面是一套可以直接照做的 429 排查流程。三步按成本从低到高排列，大部分情况在第一步就能定位。
第 1 步：读完整的 429 错误体
不要只在日志里记录状态码，要把响应体原样记录下来。不同层返回的 429 在措辞上差异明显，这是最直接的线索。
- 上游厂商返回：错误体里通常带有厂商的错误类型字段，例如 Anthropic 会给出
rate_limit_error类型，OpenAI 风格接口会给出rate_limit_exceeded一类的错误码，并说明是请求数还是 token 数超限。 - 网关返回：措辞往往提到“账户”“分组”“令牌”“渠道”等网关自身概念，或者明确写出网关名称。
- 免费档返回：会出现“free tier”“quota”“daily limit”“capacity”等字样。第三方对某些模型免费试用的测试中，就频繁遇到这种容量型 429。
如果你通过中转或聚合平台调用，要特别留意网关是否把上游原始错误透传了出来。透传说明上游在限你，非透传的自定义措辞则说明是网关在限你。
第 2 步：检查 429 响应头
响应头是第二条证据链。主流厂商会在响应头里返回剩余额度与重置时间，网关也可能附带自己的字段。
| 响应头 | 常见来源 | 含义 | 排查用途 |
|---|---|---|---|
Retry-After |
HTTP 标准，多方通用 | 建议等待的秒数 | 退避时优先采用 |
x-ratelimit-remaining-requests |
OpenAI 风格接口 | 当前窗口剩余请求数 | 判断是否为 RPM 限流 |
x-ratelimit-remaining-tokens |
OpenAI 风格接口 | 当前窗口剩余 token 数 | 判断是否为 TPM 限流 |
anthropic-ratelimit-requests-remaining |
Anthropic | 剩余请求数 | 确认限流来自 Anthropic |
anthropic-ratelimit-input-tokens-remaining |
Anthropic | 剩余输入 token 数 | 判断是否为输入 token 限流 |
判断规则很简单：出现厂商前缀的限流头并且剩余值为 0，基本可以确定是上游厂商在限你；没有任何厂商限流头，只有网关自定义字段或干脆什么都没有，则网关层的可能性更大。需要注意的是，部分厂商近年来把具体限额改为只在控制台展示，响应头里的信息可能不完整，这时要回到第 1 步的错误措辞和第 3 步的维度对比。
第 3 步：对照限流维度
知道是谁在限你之后，还要弄清楚限的是什么。不同厂商的限流规则并不统一，第三方对 5 家厂商的横向整理显示：Anthropic 主要按每分钟 token 数限制，且缓存命中的 token 不计入限额；DeepSeek 主要限制并发数；OpenAI 和 Google 的具体额度则更多放在控制台里查看。
这对配置策略有直接影响，常见对应关系如下：
- RPM（每分钟请求数）超限：把多个小请求合并成批量请求，或者在客户端加令牌桶匀速发送。
- TPM（每分钟 token 数）超限：缩短上下文、启用提示缓存，长文档任务拆分到不同时间窗口。
- 并发数超限：降低 worker 数量，用队列控制同时在途的请求数，单纯退避作用有限。
- 日配额或免费额度耗尽：退避没有意义，只能等重置、升级档位或切换到其他渠道。
第 4 种情况是唯一一种“退避注定无效”的 429，也是最应该尽早识别并直接进入故障切换的情况。
429 退避策略怎么配
确认 429 属于可恢复的速率限流后，就进入退避阶段。退避的目标不是“尽快重试”，而是“在不加重拥堵的前提下尽快恢复”。
指数退避加随机抖动
最常用的方案是指数退避（Exponential Backoff）加随机抖动（Jitter）。第 n 次重试的等待时间约为“基础延迟 × 2 的 n 次方”，再在此基础上叠加一个随机量，并设置上限。随机抖动的作用是打散多个客户端的重试时间点，避免它们在同一秒集中冲击，形成“重试风暴”。
如果响应里带有 Retry-After，它的优先级应高于你自己算出来的退避时间。服务端比你更清楚窗口何时重置，按它的建议等待，往往是最快恢复的方式。
退避参数推荐值
下表给出一组适用于大多数对话与批处理场景的起步参数，实际使用时可按业务延迟容忍度调整。
| 参数 | 推荐起步值 | 说明 |
|---|---|---|
| 基础延迟 | 1 秒 | 第一次重试前的等待时间 |
| 退避倍数 | 2 | 每次重试等待时间翻倍 |
| 最大单次等待 | 30-60 秒 | 防止等待时间无限增长 |
| 最大重试次数 | 3-5 次 | 超过后进入故障切换或报错 |
| 随机抖动 | 等待时间的 0-100% 随机 | 推荐“全抖动”方式，打散重试 |
| Retry-After | 有则优先 | 覆盖自算的退避时间 |
有两个配置细节经常被忽略。第一，交互式场景（例如聊天界面）总等待时间不宜过长，建议设置一个总超时预算，超出后直接走切换或提示用户。第二，不要对 400、401、403 这类配置错误做退避重试，它们再等多久也不会自己变好，只会白白消耗时间和配额。
如果你使用的是官方 SDK，许多 SDK 已经内置了针对 429 和 5xx 的自动重试，通常通过 max_retries 一类的参数控制次数。在自己再包一层重试之前，先确认 SDK 默认行为，避免两层重试叠加导致实际重试次数成倍放大。
429 故障切换怎么配
退避是“原地等待”，故障切换（Failover）是“换条路走”。两者不是二选一，而是先后关系：先退避，退避无效再切换。
什么时候触发故障切换
建议在以下任一条件满足时触发切换，而不是一见 429 就切：
- 达到最大重试次数，429 仍然持续返回；
- 错误措辞明确指向日配额、免费额度耗尽或“容量不足”；
Retry-After给出的等待时间超过了业务能接受的上限；- 同一渠道在短时间内连续多次失败，触发熔断阈值。
第三方对 OpenRouter 上某热门模型频繁 429 的处理建议也是同样的思路：先退避，再故障切换到同一接口下的其他模型。这样的顺序既能吃到原模型的输出质量，也能保证服务不中断。
切换链路的三种设计
故障切换的“备用路线”有不同层次，切换代价从低到高依次为：
- 同模型换渠道：同一个模型，换另一个 API Key、另一个分组或另一家供应商。输出一致性最好，是首选。
- 同厂商换档位：例如从旗舰模型降到同系列的轻量模型，能力略降但风格接近。
- 跨厂商换模型：换到另一家的同级模型，可用性最高，但提示词效果和输出格式需要提前验证。
在此之上建议加一层熔断器（Circuit Breaker）：某条渠道连续失败达到阈值后，在一段冷却时间内直接跳过它，冷却结束后放少量探测请求，恢复了再逐步放量。这能避免每个请求都先撞一次墙再切换，显著降低整体延迟。
上图对比的两种策略，在实际项目里可以通过同一个统一接口完成验证。像 API易 这类兼容 OpenAI 与 Anthropic 接口格式的平台，同一套代码只需修改 model 参数即可切换备用模型，比为每家厂商分别维护 SDK 要省事得多。
429 限流处理快速上手
下面把前面的内容整理成一份可以直接对照落地的配置清单。全文不涉及代码，你可以把它当作代码评审或运维配置时的检查表。
5 项配置检查清单
- 日志：记录完整响应体与响应头，至少包含状态码、错误类型、错误措辞、
Retry-After以及各类ratelimit字段。 - 分类：在客户端把错误分为“可退避”（429 速率类、529、503）、“需切换”（配额耗尽、持续失败）、“不可重试”（400、401、403）三类。
- 退避：按上文参数表配置指数退避加全抖动，
Retry-After优先，并设置最大重试次数与总超时预算。 - 切换链：按“同模型换渠道 → 同厂商换档位 → 跨厂商换模型”的顺序配置备用列表，提前验证每个备用模型的提示词效果。
- 熔断与告警：为每条渠道设置失败阈值与冷却时间，同时对 429 比例设置告警，持续偏高时说明需要申请提额或调整并发。
备用模型链路示例
下表是一个常见的三级切换链路示意。具体模型名以平台模型列表为准，涉及的计费请以价格页为准，本文不列具体单价。
| 层级 | 选择思路 | 接口格式 | 可用平台 | 价格口径 |
|---|---|---|---|---|
| 主用 | 业务效果最好的旗舰模型 | OpenAI 或 Anthropic 格式 | API易 apiyi.com、官方 API | 以 docs.apiyi.com/models 为准 |
| 一级备用 | 同模型的另一渠道或分组 | 与主用一致 | API易 apiyi.com、官方 API | 以 docs.apiyi.com/models 为准 |
| 二级备用 | 同厂商轻量模型或跨厂商同级模型 | OpenAI 兼容格式 | API易 apiyi.com 等聚合平台 | 以 docs.apiyi.com/models 为准 |
接入方式上，如果你使用 OpenAI 或 Anthropic 官方 SDK，通常只需要把 base_url 改成平台提供的地址、api_key 换成平台密钥即可。具体的接口地址和各模型的调用说明，建议以 API易 文档中心 docs.apiyi.com 为准，不要照搬网上未经核实的地址。
🚀 快速开始：搭建 429 容错链路时，建议先通过 API易 apiyi.com 用同一套代码接入主用和备用模型。平台提供本文涉及的主流模型 API 调用，兼容 OpenAI 与 Anthropic 接口格式，切换模型只需改
model参数。接入文档见 docs.apiyi.com，各模型输入输出单价、缓存价格与计费口径以价格页 docs.apiyi.com/models 的实际数据为准。
常见问题 FAQ
Q1：什么是 429 限流？
429 是 HTTP 标准中的 Too Many Requests 状态码，表示调用方在某个时间窗口内超过了允许的请求数、token 数、并发数或总配额。它说明的是“你被限制了”，并不说明模型本身故障。
Q2：429 和 529、503 有什么区别？
429 指向调用方的额度问题，责任在“你用得太多”；529 是 Anthropic 的过载错误，503 是服务暂不可用，责任都在服务端容量。前者优先退避和调整用量，后两者更适合短暂退避后直接故障切换。
Q3：怎样最快判断 429 来自上游厂商还是网关？
先看错误体措辞：带厂商错误类型的通常来自上游，提到账户、分组、渠道等概念的通常来自网关。再看响应头：出现厂商前缀的 `ratelimit` 字段且剩余值为 0，基本可以确认是上游在限流。
Q4：为什么退避了很多次 429 还是不恢复？
最常见的原因是限流维度判断错了。如果是日配额或免费额度耗尽，退避注定无效；如果是并发数超限，客户端仍在高并发发送，退避也只能缓解。此时应降低并发或直接进入故障切换。
Q5：如何快速搭建一套多模型故障切换链路？
推荐使用支持多模型统一接口的平台进行验证：
1. 在 API易 apiyi.com 注册账号并获取 API Key；
2. 按 docs.apiyi.com 文档配置 `base_url`，使用 OpenAI 或 Anthropic 格式接入；
3. 在客户端配置主用与备用模型列表，通过修改 `model` 参数实现切换。
这样主用和备用模型共用一套代码，切换链路的测试成本会低很多。
Q6：故障切换会不会让成本失控？
有可能。备用模型的单价、上下文长度和缓存策略都可能与主用模型不同，频繁切换会改变账单结构。建议为每个备用模型提前核对价格，统一以 API易 价格页 docs.apiyi.com/models 的实际数据为准，并对切换比例设置告警。
Q7：429 处理方案有哪些已知局限？
退避会增加请求延迟，不适合对实时性要求极高的场景；跨厂商切换可能带来输出风格和格式差异，需要提前做回归测试；部分厂商只在控制台展示限额，响应头信息不完整，排查时只能依赖错误措辞和监控数据。
429 限流处理核心要点 Key Takeaways
- 429 只说明被限制：它不说明是谁限制、限制了什么，不能直接等同于模型故障。
- 先读错误原话：错误体措辞是判断上游、网关或免费档的最快线索。
- 再看响应头：厂商前缀的
ratelimit字段与Retry-After是第二条证据链。 - 按维度对症处理：RPM 匀速、TPM 缩上下文、并发控 worker、配额耗尽直接切换。
- 先退避后切换：指数退避加全抖动，
Retry-After优先，重试有上限。 - 切换链分层设计：同模型换渠道优先，跨厂商换模型兜底，配合熔断器。
- 用统一接口降成本：通过 API易 兼容 OpenAI 与 Anthropic 格式的接口，可用一套代码管理主备模型。
总结
遇到 429 时，正确顺序是“定位来源 → 判断维度 → 退避 → 切换”，而不是一上来就换模型：
- 定位来源：错误体措辞加响应头，分清上游厂商、网关和免费档。
- 判断维度：弄清是请求数、token 数、并发还是总配额，决定退避是否有效。
- 配置容错：指数退避加抖动作为第一道防线，分层故障切换加熔断作为第二道防线。
把这套流程固化到日志、错误分类和客户端配置中，429 就从“半夜报警”变成了可预期、可自愈的常规事件。
推荐通过 API易 apiyi.com 快速验证主备模型的切换效果，接入说明见 docs.apiyi.com，涉及的模型价格与计费口径请以 docs.apiyi.com/models 为准。
📚 参考资料
- Rate Limit Reached in Claude Code: What Each 429 Message Means：Claude Code 中 429 错误信息的含义解读
- 链接：
ofox.ai/blog -
说明： 说明如何通过服务端原话区分 Anthropic、网关与免费档限流
-
Claude Code fallbackModel: 3-Tier Failover Setup：Claude Code 备用模型配置
- 链接：
ofox.ai/blog -
说明： 指出 fallbackModel 在 529 过载时触发、最多 3 个模型，而非 429
-
LLM API Rate Limits Compared：5 家大模型厂商限流规则对比
- 链接：
ofox.ai/blog -
说明： 对比按 token、按并发与仅控制台展示等不同限流口径
-
API易 文档中心与价格页：接入说明与模型计费
- 链接：
docs.apiyi.com与docs.apiyi.com/models - 说明： 接口格式、base_url 配置与各模型实际价格以此为准
作者：APIYI 技术团队
技术交流：欢迎在 API易 apiyi.com 首页联系我们交流限流与容错实践，更多接入资料可访问 docs.apiyi.com 文档中心
