报错排查

Claude Code 报 429 或「用量已达上限」:先分清是哪一种限制

Claude Code 的 429 Request rejected 和 400「用量已达上限」是不同的限制:并发、请求频率、5 小时和 7 天额度窗口。实测 Claude Code 遇到 429 会自动重试 10 次、约 3 分钟,遇到 400 立即报错。每种限制该等多久、怎么处理,附对照表。

核实于 2026-11-03 · 更新于 2026-11-03
报错原文
API Error: Request rejected (429) · 同时进行的请求过多,请等前面的请求完成后再试。
API Error: 400 本周期用量已达上限,将于 …(北京时间)重置,请稍后再试。
一句话结论

先看状态码。429 是短时间内请求太多或太密,等几十秒到几分钟就能恢复,Claude Code 会自己重试;400 加「用量已达上限」是额度窗口用完了,要等到提示里写的重置时间,重试没有用。

实测环境:Claude Code 2.1.312,Linux,2026-11-03。用本地假端点分别返回 429 和 400,记录重试次数与间隔。报错原文取自 Code2AI 服务端实际返回给用户的提示。

Claude Code 遇到 429 和 400 的不同反应

实测结果:

服务端返回 Claude Code 的行为 多久后看到报错 最终提示格式
429 自动重试 10 次,间隔逐步拉长到约 40 秒 约 3 分钟 API Error: Request rejected (429) · <原因>
429,并带 retry-after: 3 按服务端给的间隔重试(实测每次正好 3 秒) 取决于 retry-after 同上
400 不重试 立即 API Error: 400 <原因>

所以看到「卡了很久才出错」,多半是 429 在后台重试;一按回车就出错,多半是 400 类的额度问题。重试次数可以用 CLAUDE_CODE_MAX_RETRIES 调整,实测设为 2 时总共只发 3 次请求。

四种限制对照

在 Code2AI 上,四种限制的提示原文和处理方式如下。其他服务商的措辞不同,但限制类型大同小异,可以按同样的思路判断:

提示原文 状态码 是哪种限制 怎么处理
同时进行的请求过多,请等前面的请求完成后再试 429 并发:同一时刻在跑的请求太多 关掉多余的 claude 窗口,减少同时运行的子代理
请求过于频繁,请放慢速度后再试 429 频率:短时间内请求太密 等几十秒,自动重试通常能自己恢复
已超过每小时请求次数上限,请等待几分钟后再试 429 每小时请求次数 等几分钟;检查是不是有脚本在循环调用
本周期用量已达上限,将于 …(北京时间)重置 400 5 小时或 7 天额度窗口用完 等到提示里的重置时间,或升级套餐

旧版本的英文提示分别是 Too many concurrent requests、Rate limit exceeded、You've exceeded the hourly request limit、Your API usage has exceeded the usage limit for the current period,含义一一对应。

并发为什么容易超

很多人只开了一个窗口,也会碰到「同时进行的请求过多」。原因是 Claude Code 一次操作可能同时发出好几个请求:

  • 子代理(Task / Agent):一个任务拆成几个子代理并行跑,每个子代理都单独发请求。
  • 多个终端:两三个项目各开一个 claude,请求会叠加。
  • 后台会话:用 --bg 放到后台的会话也在占并发。

处理方法是让前面的请求跑完再发新的,或者在提示词里要求它串行处理,不要并行开子代理。

额度窗口:5 小时和 7 天

Code2AI 的 Claude 套餐和官方 Pro、Max 一样,用两个滚动窗口同时计量:

  • 5 小时窗口:过去 5 小时内的用量。用满后,最早的那部分用量滑出窗口,额度就会逐步恢复。
  • 7 天窗口:过去 7 天的累计用量。这个窗口用满,就要等到提示里的重置时间。

用量按模型加权计算:Sonnet、Haiku 按 1 倍计,Opus 系列按 2 倍计。也就是说,同样的任务用 Opus 跑,消耗的额度是 Sonnet 的两倍。额度紧张时,把日常改代码切到 Sonnet,只在难题上用 Opus,同一份额度能多用不少。已用额度和剩余额度在控制台实时可查,不用等报错才知道。

额度用完了还要继续用

  • 等重置:提示里写了北京时间的重置点,到点自动恢复。
  • 当天急用:「今日用量已达上限」这类提示会附上购买入口,按提示购买当日补充额度即可,付款后立即生效。
  • 长期不够用:升级到更高档位。各档价格和对应的官方档位见 Claude Pro、Max、Ultra 对比。

常见问题

429 会不会自己好?

频率类和并发类的 429 一般会。Claude Code 会自动重试约 3 分钟,多数情况下重试期间就恢复了,你只会觉得「这一步有点慢」。如果 3 分钟后还是报错,说明请求压力一直没降下来,先减少并行任务。

为什么额度用完是 400 而不是 429?

额度窗口用完不是「稍等一下就好」的情况,返回 429 只会让客户端白白重试几分钟。用 400 加明确的重置时间,Claude Code 会立即停下,把原因显示给你。

用量提示和官方 Claude 的提示一样吗?

不一样。官方订阅用量用完时,Claude Code 显示的是 Anthropic 自己的提示。用第三方端点时,提示文字由服务方决定,以服务方给出的原文为准,不要照着官方的处理建议去操作。