疑难排查 · Claude Code
Claude Code API Error 429(rate_limit_error)原因与解决方法
当账户的速率或并发上限被触达时,Claude Code 会打印 API Error: 429 rate_limit_error。为什么在 GPT 和 Gemini 模型上并行代理会触发它,以及如何解决。
你看到的报错
API Error: 429 {"type":"error","error":{"type":"rate_limit_error","message":"Rate limit reached. Please retry shortly."}}为什么会发生
- 密钥所属账户的速率或并发上限被超出。Claude Code 通过 Messages API 发送 GPT 和 Gemini 请求,该端点把这个上限报告为 429 rate_limit_error。
- 多个 Claude Code 会话或子代理在同一把密钥上并行运行——每个都在每一轮发送请求,所以突发流量叠加得比看上去快。
- 在 google/* 模型上,响应体文本来自 Gemini 一侧——Resource has been exhausted. Please retry later.——而状态码和 error.type 保持不变。
- 在引发第一个 429 的突发之上继续堆叠重试,只会让突发变大而不是消退。
如何解决
- 稍等片刻——Claude Code 会自动重试并遵守 Retry-After。如果反复出现,减少共用同一把密钥的会话数。
- 同时运行更少的子代理或并行会话——并行请求最先撞上上限。
- 不要把它和 HTTP 402 混淆——那是预付余额为空。429 是可重试的吞吐量问题。402 去充值;429 遵守 Retry-After。
- 如果你长期需要超出账户允许的吞吐量,就在脚本里限制并发并联系支持。不要把 402 当成 429 去重试。
相关搜索
claude code api error 429claude code rate limit error
常见问题
Claude Code 里的 API Error 429 是说预付余额用完了吗?+
不是。429 是吞吐量问题。预付余额为空是 HTTP 402。429 遵守 Retry-After。402 去充值。
Claude Code 会自己重试 429 吗?+
会——它会自动退避并重试。如果错误一直存在,说明突发流量补充得比窗口释放得快,通常是同一把密钥上的并行会话造成的。
在 Claude Code 里选的模型会改变 429 吗?+
openai/* 和 google/* 模型的状态码和 error.type 相同,只有文本不同:GPT 模型返回 Rate limit reached. Please retry shortly.;Gemini 模型返回 Resource has been exhausted. Please retry later.