疑难排查
Claude Code API 报错——429、401、402、529
Claude Code 把 API 故障显示为以 "API Error:" 开头、后跟原始响应体的一行文本。下面的页面逐一覆盖每种形式：报错原文、产生原因以及解决办法。
| 错误 | 含义 |
|---|---|
API Error: 429 {"type":"error","error":{"type":"rate_limit_error… | 当每分钟吞吐量耗尽时，Claude Code 会打印 API Error: 429 rate_limit_error。这个限制到底是什么、为什么并行智能体会触发它，以及如何解决。 |
API Error: 401 {"type":"error","error":{"type":"authentication_e… | 当密钥没有到达它应该访问的端点时，Claude Code 会打印 API Error: 401 invalid x-api-key。引发它的环境变量规则以及修复方法。 |
API Error: 529 {"type":"error","error":{"type":"overloaded_error… | 当上游容量饱和时，Claude Code 会打印 API Error: 529 Overloaded。为什么这不是你的请求的问题、为什么它会集中出现，以及什么才真正有用。 |
API Error: 402 {"type":"error","error":{"type":"billing_error","… | 当预付余额不足以支付本次请求时，Claude Code 会打印 API Error: 402 billing_error。去充值；不要把 402 当成限流去重试。 |
Claude Code API Error 429（rate_limit_error）报错原因与解决方法
当每分钟吞吐量耗尽时，Claude Code 会打印 API Error: 429 rate_limit_error。这个限制到底是什么、为什么并行智能体会触发它，以及如何解决。
Claude Code API Error 401 invalid x-api-key 解决方法
当密钥没有到达它应该访问的端点时，Claude Code 会打印 API Error: 401 invalid x-api-key。引发它的环境变量规则以及修复方法。
Claude Code API Error 529 Overloaded 是什么意思
当上游容量饱和时，Claude Code 会打印 API Error: 529 Overloaded。为什么这不是你的请求的问题、为什么它会集中出现，以及什么才真正有用。
Claude Code API Error 402 billing_error — 余额不足
当预付余额不足以支付本次请求时，Claude Code 会打印 API Error: 402 billing_error。去充值；不要把 402 当成限流去重试。
全部工具 · Claude API 错误码 · 配置指南