如果 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 秒快速诊断第一件要确认的事你到底看的是哪个报错因为修法岔得很厉害。你在终端里看到的HTTP 状态什么意思第一步动作API Error: Request rejected (429)429你的账户超过了它自己的每分钟限额RPM/ITPM/OTPM读retry-after然后降并发或加缓存API Error: Server is temporarily limiting requests (not your usage limit)429加速限额流量陡增后的短暂限流稍等片刻再逐步放量API Error: Repeated 529 Overloaded errors529Anthropic 的服务器对所有人满载等待或/model切到负载较轻的模型。见报错排查手册里的 529 部分Youve hit your weekly limit · resets Mon不适用订阅Pro/Max 套餐额度不是 API 429见用量上限指南按顺序跑这份清单确认是 429不是 529。Claude Code 对两者用不同的措辞。「Request rejected (429)」或「Rate limited」是你的账户。「529 Overloaded」是服务器。区别对待。检查当前生效的是哪个凭据。跑/status。shell 里一个游离的ANTHROPIC_API_KEY可能把你路由到一个低 Tier 的 key 上而不是你以为在用的那个账户。看你的 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:30Zretry-after是重试前要等的秒数提前重试会失败。anthropic-ratelimit-*-limit、-remaining和-reset这几个头对请求、输入 token、输出 token 各有一份所以你能盯住每个维度的余量、在踩线之前就退避而不是踩了之后才退。有一个这个领域吃过亏才学会的注意点retry-after是服务器的提示在滚动窗口的边界上它可能读得偏短一点。把它当作一个下限来遵守再在上面加正向抖动这样一队 worker 才不会全在同一毫秒醒来重试。报错与症状 → 原因 → 修法症状可能的原因修法派生子代理后几秒内 429并发同时扇出 RPM 和 ITPM调低CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY少派子代理单个大回合、没并行也 429一个回合的上下文超过 ITPMTier 1 Sonnet 30k用/compact或/clear削上下文开 prompt 缓存安静一阵后突增、随即 429用量陡增触发加速限额逐步放量保持稳定的请求速率出现 429但仪表盘显示还有配额看的是消费上限不是每分钟 rate limit每分钟上限和月度消费上限是两回事看 rate-limit 图表retry-after在多次重试里越来越大你在结构上超了限额重试越堆越多别再加大重试升 Tier 或池化容量本该在高 Tier 上的 CI 里 429游离的ANTHROPIC_API_KEY路由到了低 Tier 的 key跑/status取消那个错的 key它为什么会踩线并发、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_CONCURRENCY2 # Surface failures faster in scripts instead of retrying 10x export CLAUDE_CODE_MAX_RETRIES3 claudePaid / 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_afterNone): 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_WATCHDOG1让 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 limitSonnet 4.x 和 Opus 4.x决定你多快踩到 429 的每分钟上限出自官方 rate-limits 文档Tier达标所需充值Sonnet 4.x RPM / ITPM / OTPMOpus 4.x RPM / ITPM / OTPMTier 1$550 / 30,000 / 8,00050 / 500,000 / 80,000Tier 2$401,000 / 450,000 / 90,0001,000 / 2,000,000 / 200,000Tier 3$2002,000 / 800,000 / 160,0002,000 / 5,000,000 / 400,000Tier 4$4004,000 / 2,000,000 / 400,0004,000 / 10,000,000 / 800,000Opus 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 区和支持帖模式触发条件怎么修子代理扇出硬失败6 个并行子代理跑在大上下文上调低并发上限减少扇出529 被误标成「Rate limited」并行会话期间服务器过载认清那是 529、不是你的配额等待或/model切换仪表盘「有可用配额」却 429把月度消费上限和每分钟 rate limit 搞混看 rate-limit 图表别看消费图表/batch式突发被拒429很多请求在一个紧窗口里打出错开请求尊重令牌桶CI 循环反复踩同一条限额固定间隔、没抖动的重试指数退避加随机抖动这些是机制层面的模式不是一份公开的事故日志。贯穿始终的是同一件事找出你正在打满的那个维度然后要么给它减速、要么把它拓宽。当你需要更多余量现在就管用的最佳替代方案如果你的瓶颈是某一个组织的每分钟上限下面是几条现实可行的选项ofox 列在前面。ofox 池化容量一个 key、按量计费。ofox 在https://api.ofox.io/v1暴露一个 OpenAI 兼容端点用一个 API key 把请求路由到多个模型上、走池化的按量计费容量。因为请求是从共享容量里取、而不是从你单个低 Tier 组织的桶里取一个突发的代理工作负载就不太容易把某一家供应商的每分钟上限打满。你保持同样的 OpenAI SDK 形状换个 model 字符串就换模型。它不能推翻每分钟 token 的物理规律但能给突发工作负载更多踩线之前的空间。from openai import OpenAI client OpenAI(base_urlhttps://api.ofox.io/v1, api_keyYOUR_OFOX_KEY) resp client.chat.completions.create( modelanthropic/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 容量事件——如果是那修法是耐心不是改配置。FAQClaude Code 里的 API Error: Rate Limit Reached 是什么意思它的意思是 Claude API 返回了 HTTP 429你的组织每分钟发的请求数或 token 数超过了你账户 Tier 允许的额度。这是账户侧对 RPM、ITPM 或 OTPM 的限流不是服务器宕机。响应里带一个retry-after头告诉你要等多少秒。Claude Code 里的 429 和 529 是一回事吗不是。429rate_limit_error是说你的账户超过了它自己的每分钟限额。529overloaded_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 是 $5Tier 2 是 $40Tier 3 是 $200Tier 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 吗你可以把负载摊到多个供应商上或者用一个池化网关。像 ofoxhttps://api.ofox.io/v1这样的 OpenAI 兼容网关用一个 key 把请求路由到多个模型上、走按量计费的池化容量所以单个项目不太容易把某一个组织的每分钟上限打满。它不能改写物理规律但能拓宽余量。429 是 API 在给你定速不是把门摔上。读retry-after、给你正在打满的那个维度减速活就继续往前走。本次更新核对过的资料Anthropic API Rate Limits 参考Tier 表、RPM/ITPM/OTPM、retry-after 和anthropic-ratelimit-*头、以及缓存感知的 ITPM2026-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 核实