Claude Code 429 限流怎么办？别慌，一张表分清额度、限流和 Codex 的 429
Claude Code 报 429，可能是 Pro/Max 额度用完、API key 被限流，也可能是每月消费上限，办法各不相同。提示原文、该看哪些响应头、Claude Code 会自动重试什么，以及 Codex 怎么区分限流和 insufficient_quota。
buffer关于作者约 8 分钟阅读
遇到 Claude Code 429 限流，先别急着重试，要先弄清楚是哪一种限制。用 Pro 或 Max 订阅的话，多半是 5 小时会话额度或者每周额度用完了，Claude Code 会提示“You’ve hit your session limit”，后面带着重置时间。用 API key 的话，是你的 key 或组织触发了速率限制，提示是“Request rejected (429)”。Codex 也一样，429 背后可能是 ChatGPT 套餐额度用完、短时间请求太多，或者 API 余额不够。下面把两个工具的 429 提示原文、该看哪些响应头、每种情况怎么办整理成一份速查表，内容都来自官方文档或工具自己的源码，链接都放在正文里。
Claude Code 429 限流到底是什么意思
HTTP 429 的意思是“请求太多”。在 Claude API 里，它对应的错误类型是 rate_limit_error。Claude API 错误文档列了三种原因：组织触发了速率限制，达到了所在等级的每月消费上限，或者达到了 Claude Code 工作区的消费上限。
对大多数人来说，Claude Code 还有一个更常见的来源，就是订阅额度。用 Pro 或 Max 账号登录时，你有一个 5 小时会话额度和一个每周额度。Anthropic 的Pro 和 Max 帮助文章写明，这些额度由 Claude 和 Claude Code 共用。额度用完后，服务器返回的 429 会带上套餐的额度响应头，Claude Code 再把它翻译成一句能看懂的提示。
429 限流的几种提示和对应办法
下面这些提示都出自 Claude Code 错误参考文档，我按背后的原因分了组。
| 提示原文 | 背后的原因 | 怎么办 |
|---|---|---|
| You’ve hit your session limit · resets 3:45pm | Pro 或 Max 的 5 小时会话额度用完 | 等到提示里的重置时间，或者用额外用量 |
| You’ve hit your weekly limit · resets Mon 12:00am | 每周额度用完 | 同上，但可能要等好几天 |
| You’ve hit your Opus limit / Sonnet limit | 某一个模型系列的额度用完 | 用 /model 换到其他系列的模型 |
| Request rejected (429) | API key、Amazon Bedrock 或 Google Cloud 项目的速率限制 | 运行 /status，检查账户等级，少开几个并行代理 |
| Server is temporarily limiting requests (not your usage limit) | Anthropic 那边的短时限流 | 稍等一下再发 |
文档里有几个细节容易被忽略。会话额度和每周额度是所有模型共用的，所以这两种情况下 /model 没用；Opus 和 Sonnet 的系列额度只管各自的模型。/usage 可以看额度和重置时间，/usage-credits 可以在 Pro 和 Max 上购买额外用量。如果不想守着等重置，Claude Code v2.1.234 及以后的版本可以在当前会话里等额度重置后自动继续，命令行的开关在 /config 里，叫“Continue automatically at usage limit”。
我见得最多的坑，是明明开了订阅，却报“Request rejected (429)”。文档直接点明了原因：环境里多出来的 ANTHROPIC_API_KEY 会让请求走一个低等级的 key，而不是走你的订阅。运行 /status 看一下当前用的是哪个凭据，不是你想用的就把这个变量删掉。
429 以外的 Claude Code 报错，我在 Claude Code 常见报错和解决办法里整理过。会话额度和每周额度怎么计算，可以看 Claude 额度是怎么算的。
遇到 429 时看哪些响应头
如果你自己调用 API，或者在 Claude Code 里用 API key，想知道离限制还有多远，响应头比错误信息有用得多。Claude 速率限制文档列出了这些响应头：
| 响应头 | 含义 |
|---|---|
retry-after | 要等多少秒再重试。不是每个 429 都有，消费上限触发的 429 一定没有 |
anthropic-ratelimit-requests-remaining | 触发限制前还能发多少个请求 |
anthropic-ratelimit-tokens-remaining | 当前最严格那条限制下还剩多少 token，按千取整 |
anthropic-ratelimit-input-tokens-remaining / -output-tokens-remaining | 输入和输出 token 各剩多少 |
anthropic-ratelimit-*-reset | 这条限制完全恢复的时间，格式是 RFC 3339 |
这些限制有两点值得了解。第一，API 用的是令牌桶算法，额度是持续回填的，不是到某个固定时间一次性重置。第二，限制按每个模型类别的每分钟请求数、每分钟输入 token 数和每分钟输出 token 数分别计算，所以请求不多的时候，也可能因为 token 太多触发 429。你可以在 Claude Console 的速率限制页面看到自己组织的限制。
等待没用的情况是消费上限。每个等级都有每月上限，Start 是 500 美元，Build 是 1,000 美元，Scale 是 200,000 美元，达到后 API 会暂停到下个月 1 号 00:00 UTC，也就是北京时间 1 号早上 8 点。这时返回的仍然是 429 rate_limit_error，但没有 retry-after 响应头，错误代码是 enforced_spend_limit_reached。在恢复之前，怎么重试都会失败，包括 SDK 的自动重试。
Claude Code 自己会重试哪些 429
对短时的 429 限流，Claude Code 会先用指数退避自己重试，默认最多 10 次，然后才把错误显示给你。用 claude.ai 订阅登录时，从 v2.1.199 开始，不带套餐额度响应头的 429 也会自动重试。真正的套餐额度用完不会重试，因为不到重置时间重试也没用；网关的消费上限 429 也不会重试。设置备用模型同样帮不上忙，模型配置文档写明速率限制错误不会触发备用模型。
在 CI 这类没人看着的场景里，可以设 CLAUDE_CODE_RETRY_WATCHDOG=1，让 Claude Code 对 429 和 529 容量错误无限重试。从 v2.1.239 开始，遇到消费上限或余额不足的 429 时它会直接失败，不会一直重试下去。
Codex 的 429：限流和 insufficient_quota 的区别
Codex 会根据服务器随 429 返回的内容显示不同的提示。我看了开源的 Codex CLI 里的错误处理代码，它是这样区分的：
| 服务器返回 | Codex 显示 | 怎么办 |
|---|---|---|
usage_limit_reached | You’ve hit your usage limit，知道重置时间时会带上 | 运行 /status，等重置，买额外额度或者改用 API key |
usage_not_included | To use Codex with your ChatGPT plan, upgrade to Plus | 你的套餐不包含 Codex |
insufficient_quota、credit_balance_exhausted 或消费上限代码 | Quota exceeded. Check your plan and billing details. | 充值或调高上限，重试没用 |
| 其他 429 | exceeded retry limit, last status: 429 Too Many Requests | 等一等，少开几个并行会话 |
第一行是 ChatGPT 套餐额度。OpenAI 的 Codex 价格页写着 Plus 和 Business 有 5 小时额度，Pro 目前没有 5 小时额度，另外还可能有每周额度。额度用完后，Plus 和 Pro 用户可以买额外额度，所有用户也都可以用 API key 在本地继续用，按 API 价格计费。
第三行是账单问题。OpenAI 的 API 错误代码文档给余额用完、组织消费上限和项目消费上限分别列了代码，并说明更宽泛的错误类型仍可能是 insufficient_quota。文档还写明，重试账单、消费上限或额度类错误不会恢复 API 访问。所以 Codex 提示“Quota exceeded”时，去账单页处理，不要干等。
最后一行是普通的速率限制。Codex 默认会把 HTTP 请求重试 4 次（配置参考里的 request_max_retries），还不行才显示这条提示。OpenAI 的速率限制文档说，临时 429 可能带 Retry-After，要把它当作最少等待时间，再加一点随机延迟。x-ratelimit-remaining-requests、x-ratelimit-remaining-tokens 和对应的 x-ratelimit-reset-* 响应头会告诉你还剩多少、多久恢复。OpenAI 还有一种代码为 slow_down 的 429，意思是请求量涨得太快了。
不是 429 的两种报错
有两种报错看起来很像，其实和你的额度无关。在 Claude 这边，529 overloaded_error 表示 Anthropic 这个模型的算力不够，不计入你的额度，用 /model 换个模型往往就能解决，详细的我写在 Claude Code 529 Overloaded 是什么意思。在 Codex 这边，对应的是 503，Codex 显示为“Selected model is at capacity”，可以看 Selected model is at capacity 是什么意思。
额度明明还有却报 429
有时候数字对不上，两个工具都有用户报告过。Claude Code 的 #96872 号 issue（2026 年 9 月）里，一位用户记录到 195 条 rate_limit_error，而当时会话额度和每周额度只用了 27% 和 26%，同时开着大约 6 个会话。Codex 那边，#57072 号 issue（2026 年 10 月 26 日）报告每周额度还剩 99% 时出现 429，这位用户重新登录后暂时恢复了。
如果你也是这种情况，先在对应工具里运行 /status，关掉多余的会话，再重新登录。数字还是对不上的话，带上请求 ID 去提交报告。Claude 的请求 ID 在 request-id 响应头里，Codex 有请求 ID 时会把它显示在重试次数用完那条提示的末尾。两家都没有说明并行会话怎么计入这些限流，所以别默认多开会话不占额度。
如果你还在两个工具之间犹豫，我在 Claude Code 和 Codex 该买哪个里比较过价格和额度。
Claude Code 429 限流常见问题
换模型能解决 429 限流吗？
只对 Opus 或 Sonnet 系列额度有用。会话额度和每周额度是所有模型共用的，/model 解决不了。
遇到 429 限流要等多久？
看提示里的重置时间。API 返回的 429 如果带 retry-after，就按它等。如果是等级消费上限，没有 retry-after，会一直持续到下个月 1 号 00:00 UTC，除非你申请到了更高的上限。
Max 套餐几乎没怎么用，为什么也报 429？
运行 /status，看看环境里是不是设了 ANTHROPIC_API_KEY，设了的话 Claude Code 会用这个 key，而不是你的订阅。订阅确实生效还是报错的话，可能是短时限流，或者上面提到的那类 bug。
Codex 提示 Quota exceeded，重试有用吗？
没用。OpenAI 明确说重试账单、消费上限或额度类错误不会恢复访问，要先充值或调高消费上限。