Claude Code 撞到 429 rate limit：原因和 6 招修复（2026）

如果 Claude Code 说「Rate limit reached」，是 API 在告诉你：你花光了每分钟的 token 或请求预算，不是 Anthropic 宕机了。修法就是读一个头、然后给对的那个维度减速。

你跑了几个并行子代理、或者一个长的代理循环，Claude Code 停下来，红着一行字提到 rate limit 或者「Request rejected (429)」。什么都没坏。你撞到了你账户 Tier 设的某条每分钟上限，API 在让你等确定的秒数再重试。

这篇讲的是你作为按 token 计费的 Console / API key 用户拿到的 API 侧 429。如果你用的是 Pro 或 Max 订阅、撞到的是周限或会话限额而不是 429，那是另一套机制、另一种修法，见《Claude Code 用量为什么掉得这么快》。

30 秒快速诊断

第一件要确认的事：你到底看的是哪个报错，因为修法岔得很厉害。

按顺序跑这份清单：

1. 确认是 429，不是 529。 Claude Code 对两者用不同的措辞。「Request rejected (429)」或「Rate limited」是你的账户。「529 Overloaded」是服务器。区别对待。
2. 检查当前生效的是哪个凭据。 跑 /status。shell 里一个游离的 ANTHROPIC_API_KEY 可能把你路由到一个低 Tier 的 key 上，而不是你以为在用的那个账户。
3. 看你的 Tier。 在 Console 里打开 Limits 页面。Tier 1 很紧：Sonnet 4.x 是 50 RPM、30,000 ITPM。一个大上下文的回合加一个子代理就能超。

什么时候该修 429（什么时候干脆等）

动手重构之前先想清楚，因为有些 429 会自己消失、有些需要真改东西。

什么时候只管重试和等。 如果你在一次突发里看到偶发的 429、而 retry-after 很小（几秒），那就不用做结构性的事。Claude Code 自己已经会对瞬时的 429 和 529 容量错误用指数退避重试至多 10 次再把错误抛出来，会显示一个 Retrying in Ns · attempt x/y 的倒计时。如果报错率低于大约 5% 的请求，重试就是全部的修法。

什么时候真要改点什么。 如果 429 持续不断、如果它在任务中途打死子代理、或者 retry-after 一直往上爬，那你就是在结构上超出了你 Tier 的每分钟预算。降并发、加缓存、或者升 Tier。对一条已经打满的限额堆更多重试，只会排更多的失败。

停止规则。 如果你在 Tier 1 上对一个大仓库跑并行子代理，再多的退避也撑不住。要么升到更高的 Tier，要么用一个网关把容量池化。退避能抹平尖峰，但抬不了天花板。

「Rate Limit Reached」和 HTTP 429 到底是什么意思

429 是 Claude API 在你的组织超过它某条每分钟 rate limit 时返回的 HTTP 状态。它是一个账户级的信号，作用范围是你的组织，并且对每个模型分别强制。错误体是一个 rate_limit_error，消息会指明你撞的是哪条限额，例如「This request would exceed your organization’s rate limit of x0,000 input tokens per minute.」API 还会附上一个 retry-after 头。

Messages API 强制的每分钟维度有三个，详见 Anthropic 的 rate-limits 文档：

• RPM（每分钟请求数）：你能发多少次 API 调用。
• ITPM（每分钟输入 token 数）：你能发多少输入 token。这是咬代理工作负载的那一条，因为每一回合都把整段对话上下文当输入发出去。
• OTPM（每分钟输出 token 数）：模型每分钟能为你生成多少 token。注意：max_tokens 不计入 OTPM，只有实际产出的 token 才算，所以设一个很高的 max_tokens 对 rate limit 没有坏处。

你一旦越过这三条中的任意一条就立刻拿到 429。这条限额用的是令牌桶算法，所以你的容量是连续回填的，而不是每分钟开头重置一次。这也意味着即便你按分钟平均的用量看着没问题，短促的突发也能触发限额：60 RPM 的执行更接近每秒 1 个请求，而不是 60 个请求一次性打出去。

每个 429 背后都是三个数字在管：每分钟的请求、输入 token、输出 token。找出你正在冲破的是哪一个，修法自己就选好了。

429 响应，以及那些把一切告诉你的头

当你撞到限额，响应会带上几个头，告诉你限额、你剩下的预算、以及它什么时候回填。这些值得在你自己搭的任何代理循环里暴露出来：

HTTP/1.1 429 Too Many Requests
retry-after: 12
anthropic-ratelimit-input-tokens-limit: 30000
anthropic-ratelimit-input-tokens-remaining: 0
anthropic-ratelimit-input-tokens-reset: 2026-06-24T18:42:30Z

retry-after 是重试前要等的秒数；提前重试会失败。anthropic-ratelimit-*-limit、-remaining 和 -reset 这几个头对请求、输入 token、输出 token 各有一份，所以你能盯住每个维度的余量、在踩线之前就退避，而不是踩了之后才退。

有一个这个领域吃过亏才学会的注意点：retry-after 是服务器的提示，在滚动窗口的边界上它可能读得偏短一点。把它当作一个下限来遵守，再在上面加正向抖动，这样一队 worker 才不会全在同一毫秒醒来重试。

报错与症状 → 原因 → 修法

它为什么会踩线：并发、token 突发、没退避

几乎每个 Claude Code 的 429 都来自三种模式。

并行子代理和并行会话。 这是大头。当 Claude Code 通过 Task 工具扇出子代理时，每个子代理都是一条独立的请求流，而每一条都把自己那份上下文当输入 token 带着。在一个大仓库上跑六个子代理，你的 ITPM 和 RPM 会同时飙起来。有一个已知的 Claude Code issue记录了 5-10 个并行会话发起子代理扇出、在容量错误下硬失败的情况。减少扇出，429 就停了。

紧 Tier 上的上下文突发。 在 Tier 1 上，Sonnet 4.x 拿到 30,000 ITPM。如果你的对话上下文已经长到 25,000 token，一条新消息就吃掉你大部分的每分钟输入预算，同一分钟内的第二条消息就触发 429。这就是「prompt 膨胀」：会话长得超过了任务的需要。跑 /context 看是什么在塞满窗口，然后 /compact 或 /clear。

你自己脚本里没退避。 Claude Code 本身会用指数退避重试。但如果你是在 Claude Code 周边直接打 API（一个 CI 包装、一个自定义代理循环），而你按固定间隔、没有抖动地重试，那每个 worker 就会齐步重试、一起再次踩线。同步的重试，正是一次短暂限流变成持续故障的方式。

怎么修：按 Tier 分档的方案

Free / Tier 1 方案：读头、削突发

如果你在最低档，你的余量最少，所以照此行事。

• 遵守 retry-after。 等头里说的秒数，再加抖动。别提前重试。
• 缩小上下文。 在自然断点跑 /compact，或者 /clear 重新开始。每回合上下文越少，每个请求的 ITPM 越低。
• 把并发降到接近串行。 把并发上限设低，别去扇出你付不起的请求。

# Lower tool-use concurrency before a heavy session
export CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY=2
# Surface failures faster in scripts instead of retrying 10x
export CLAUDE_CODE_MAX_RETRIES=3
claude

Paid / Tier 2-3 方案：缓存加指数退避

一旦你有了些余量，杠杆就是缓存加上有纪律的重试。

Prompt 缓存压的是 ITPM，不只是成本。 在大多数当前的 Claude 模型上，cache_read_input_tokens 不计入你的 ITPM 限额。Anthropic 自己的例子：在 2,000,000 ITPM 上限、80% 的缓存命中率下，你实际上每分钟能处理约 10,000,000 个总输入 token，因为缓存的那 8M 对 rate limit 是免费的。缓存你的系统 prompt、工具定义和大块上下文文档。关于从头到尾削减 token 用量的机理，见《Claude Code Token 优化：把账单砍 60-90% 的 5 个策略》。

当循环在你自己手里时，带抖动的指数退避是正确的重试形状：

import random, time

def backoff_sleep(attempt, retry_after=None):
    if retry_after is not None:        # honor the server hint as a floor
        base = float(retry_after)
    else:
        base = min(2 ** attempt, 60)   # 1, 2, 4, 8 ... capped at 60s
    time.sleep(base + random.uniform(0, base * 0.25))  # add jitter

对于像 CI 这样的无人值守运行，你还可以设 CLAUDE_CODE_RETRY_WATCHDOG=1，让 Claude Code 对 429 和 529 容量错误无限重试，而不是在 CLAUDE_CODE_MAX_RETRIES 次后放弃。

Enterprise / Tier 4 方案：抬高天花板或把它池化

当退避和缓存都不够了，你需要更多限额。

• 升你的 Tier。 Tier 会随着累计充值额度达到各门槛自动升。Tier 4 给 Sonnet 4.x 4,000 RPM 和 2,000,000 ITPM，对比 Tier 1 的 50 RPM / 30,000 ITPM。要超过 Tier 4 的限额，联系 Anthropic 销售申请定制或 Priority Tier 限额。
• 设按工作区的上限，让一个项目没法饿死组织里其他人。工作区限额会按限制器类型切分组织的每分钟预算。
• 把负载摊到多个供应商，或者池化容量。 如果你的工作负载是突发的、而单个组织的每分钟上限是瓶颈，那在多个供应商前面放一层路由就能拓宽有效天花板。关于这个模式的更多内容，见《一个 API 路由多模型，把贵活和便宜活分开》。

Anthropic 各 Tier 的 rate limit（Sonnet 4.x 和 Opus 4.x）

决定你多快踩到 429 的每分钟上限，出自官方 rate-limits 文档：

Opus 4.x 的限额是 Opus 4.8、4.7、4.6、4.5、4.1 共享的一个总额。Sonnet 4.x 的限额由 Sonnet 4.6 和 4.5 共享。在同一家族里切版本不会给你一个新桶。有个细节有帮助：限额是按模型分别施加的，所以一个 Opus 任务和一个 Sonnet 任务各从自己的池子里取、同时各自跑到各自的上限。把你那些便宜的高量活路由到 Haiku 4.5，就能把它们完全挡在 Opus 和 Sonnet 的桶之外。

加速限额：那个跟你 Tier 无关的 429

还有第二种 429 值得知道，因为它会让那些离 Tier 上限还远的人吃一惊。如果你组织的用量陡然跳升，API 可能施加一个加速限额、返回 429，哪怕你的每分钟上限还有余量。它的用意是拦住失控的尖峰，不是惩罚稳定使用。修法不是「升我的 Tier」，而是「逐步放量」。让一个新工作负载在一两分钟里热起来，而不是从冷启动就打出峰值流量，并把你的请求速率保持得大致一致。在 Claude Code 里，这个限流就是 Server is temporarily limiting requests (not your usage limit) 这条消息背后的东西，CLI 在把它抛出来之前已经替你重试过了。

摊开负载，别堆在一起

大多数代理的 429 都来自把所有事挤在一个紧窗口里做。几个便宜的调度习惯，就能让同样的总工作量塞进同样的上限里：

• 把贵的回合串行化。 在 Tier 1 上，一个大上下文的回合就可能是你那一分钟 ITPM 的大头。把这些一个一个跑，别让子代理并行地一齐打出去。
• 把不急的活批处理。 如果一个任务不需要实时答案，Message Batches API 有它自己独立的限额，所以把批量活挪过去能腾出你交互式的 RPM 和 token 预算。
• 错开 CI 任务。 别把十条流水线安排在同一个 cron 分钟启动。错开它们的启动时间，让它们的第一波突发不撞在同一个桶上。

我们在 2026 年观察到的常见失败模式

这个领域反复报上来的几种形状，取自 Claude Code 的 issue 区和支持帖：

这些是机制层面的模式，不是一份公开的事故日志。贯穿始终的是同一件事：找出你正在打满的那个维度，然后要么给它减速、要么把它拓宽。

当你需要更多余量：现在就管用的最佳替代方案

如果你的瓶颈是某一个组织的每分钟上限，下面是几条现实可行的选项，ofox 列在前面。

ofox 池化容量（一个 key、按量计费）。 ofox 在 https://api.ofox.ai/v1 暴露一个 OpenAI 兼容端点，用一个 API key 把请求路由到多个模型上、走池化的按量计费容量。因为请求是从共享容量里取、而不是从你单个低 Tier 组织的桶里取，一个突发的代理工作负载就不太容易把某一家供应商的每分钟上限打满。你保持同样的 OpenAI SDK 形状，换个 model 字符串就换模型。它不能推翻每分钟 token 的物理规律，但能给突发工作负载更多踩线之前的空间。

from openai import OpenAI
client = OpenAI(base_url="https://api.ofox.ai/v1", api_key="YOUR_OFOX_KEY")
resp = client.chat.completions.create(
    model="anthropic/claude-opus-4.8",
    messages=[{"role": "user", "content": "Refactor this function for clarity."}],
)

升你的 Anthropic Tier。 如果你想留在单一供应商，这是最干净的修法：充值到下一档，你的 RPM/ITPM/OTPM 立刻跳上去。最适合流量可预测、能承诺消费的情况。

在你自己这边做多供应商路由。 跑你自己的路由器，把请求摊到多个供应商上、并尊重每一个的 retry-after。控制力最强，要维护的代码也最多。一个 API 路由多模型讲了这个设计。

怎么监控 rate limit、抢在 429 之前动手

你能在 429 落地之前看到它来。三个地方可以盯：

• Console 的 Usage 页面有两张 rate-limit 图表：每分钟未缓存输入 token 的每小时峰值对照你当前的 ITPM 上限，输出 token 同理。它还显示你的缓存命中率，这告诉你缓存为你买到了多少 ITPM 余量。
• 响应头（anthropic-ratelimit-*-remaining 和 -reset）让你自己的代码主动限速。当剩余输入 token 接近零时，在桶空之前就减速。
• Anthropic 状态页 status.claude.com 告诉你一波「rate limited」消息是不是其实是一次影响所有人的 529 容量事件——如果是，那修法是耐心，不是改配置。

FAQ

Claude Code 里的 API Error: Rate Limit Reached 是什么意思？ 它的意思是 Claude API 返回了 HTTP 429：你的组织每分钟发的请求数或 token 数超过了你账户 Tier 允许的额度。这是账户侧对 RPM、ITPM 或 OTPM 的限流，不是服务器宕机。响应里带一个 retry-after 头，告诉你要等多少秒。

Claude Code 里的 429 和 529 是一回事吗？ 不是。429（rate_limit_error）是说你的账户超过了它自己的每分钟限额。529（overloaded_error）是说 Anthropic 的服务器对所有人暂时满载，跟你的用量无关。Claude Code 用不同的措辞显示它们：「Request rejected (429)」对「Repeated 529 Overloaded errors」。

撞到 429 rate limit 之后该等多久？ 读 retry-after 头。它给出你能重试之前要等的确切秒数；提前重试还会失败。如果这个头缺失，就退回到指数退避，从大约 1-2 秒起步、每次翻倍，再加上随机抖动，这样并行的 worker 才不会在同一瞬间一起重试。

为什么 Claude Code 一上子代理就这么快撞到 rate limit？ 并行子代理会扇出很多并发请求，而每一个都把整段对话上下文当作输入 token 带着。在大上下文上跑几个子代理，就能在几秒内冲破你的 ITPM 上限。把 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY 调低，或者减少你一次性派生的子代理数量。

Anthropic 的 rate limit 里的 RPM、ITPM、OTPM 是什么？ RPM 是每分钟请求数，ITPM 是每分钟输入 token 数，OTPM 是每分钟输出 token 数。Messages API 对每个模型类别同时强制这三项。你一旦超过其中任意一项就拿到 429，报错会指明你撞的是哪条限额。

怎么提高我的 Claude API rate limit？ 用量 Tier 会随着你累计的充值额度达到各个门槛自动升级（Tier 1 是 $5，Tier 2 是 $40，Tier 3 是 $200，Tier 4 是 $400）。更高的 Tier 会抬高 RPM、ITPM 和 OTPM。要超过 Tier 4 的限额，就联系 Anthropic 销售申请定制或 Priority Tier 限额。

Prompt 缓存对 429 rate limit 报错有帮助吗？ 有。在大多数当前的 Claude 模型上，cache_read_input_tokens 不计入你的 ITPM 限额。在 2,000,000 ITPM 上限下、80% 的缓存命中率，你实际上每分钟能处理约 10,000,000 个总输入 token，因为缓存的那部分对 rate limit 是免费的。

换供应商能避开 Claude Code 的 rate limit 吗？ 你可以把负载摊到多个供应商上，或者用一个池化网关。像 ofox（https://api.ofox.ai/v1）这样的 OpenAI 兼容网关，用一个 key 把请求路由到多个模型上、走按量计费的池化容量，所以单个项目不太容易把某一个组织的每分钟上限打满。它不能改写物理规律，但能拓宽余量。

429 是 API 在给你定速，不是把门摔上。读 retry-after、给你正在打满的那个维度减速，活就继续往前走。

本次更新核对过的资料

• Anthropic API Rate Limits 参考：Tier 表、RPM/ITPM/OTPM、retry-after 和 anthropic-ratelimit-* 头、以及缓存感知的 ITPM（2026-06-24 核实）
• Claude Code 错误参考：「Request rejected (429)」和「Server is temporarily limiting requests」的精确字符串，以及 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY、CLAUDE_CODE_MAX_RETRIES、CLAUDE_CODE_RETRY_WATCHDOG 和自动重试行为（2026-06-24 核实）
• Claude Code issue #68502：并行子代理、429 与 529 误标、以及没退避的硬失败（2026-06-24 核实）
• ofox 模型页面：当前 Claude 旗舰（Opus 4.8）和 OpenAI 兼容端点（2026-06-24 核实）