疑难排查 · 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 429
  • claude 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.

跳过折腾坏掉的配置

apiToken.sale 通过 OpenAI 兼容端点、Messages(Anthropic 格式)端点和原生 Gemini 端点提供 GPT 与 Gemini 模型——标准 SDK、一把密钥、一个预付余额。把你工具的 base URL 指向它,本页的配置即可原样生效。