编码过程中达到速率限制
账号、工作区、模型或路由发送的请求数或 Token 数超过限制。
降低并行 Agent 数 · 缩短上下文Claude Code API 故障排查
解决 Claude Code 限流、500、529 过载和 API Key 混淆
一份覆盖 API Key 配置、Pro 或 Max 与 API 计费、Messages 兼容端点、限流、服务端错误和路由过载的排查手册。
claude-code-diagnostics
$ claude-code run --model claude-sonnetAPI 错误：达到速率限制status=429 route=messages tokens=128k retries=3下一步：降低并发、核对 Key、退避重试
4 类错误1 份手册0 个薄内容页
社区信号
开发者在公开讨论中反复追问什么
把 Reddit 和 X 上反复出现的问题整理成稳定、可核实的排查提示。
API Key 与 Pro 或 Max 订阅的区别
检查实际使用的 Key、Base URL 和计费来源，不要假设订阅套餐与 API 额度共用同一余额。
检查模型权限 · 分开检查订阅登录和 API 计费Agent 循环中出现 500 或 529
供应商或路由返回服务端故障。一次重试可能恢复；持续失败需要核对路由证据。 上游服务负载过高，通常更换 API Key 无法解决。
记录 request id · 执行退避错误地图
先看状态码，不要先听猜测
最快的办法是先分清 Key、额度、服务端错误和过载问题。
429
达到速率限制
账号、工作区、模型或路由发送的请求数或 Token 数超过限制。
- 降低并行 Agent 数
- 缩短上下文
- 退避后重试
- 检查当前额度和模型限制
500
API 服务端错误
供应商或路由返回服务端故障。一次重试可能恢复；持续失败需要核对路由证据。
- 记录 request id
- 只重试一次
- 重复失败时切换路由
- 不要先改写提示词
529
上游过载
上游服务负载过高，通常更换 API Key 无法解决。
- 执行退避
- 使用备用模型
- 减小请求体
- 检查支持或状态频道
401/403
API Key 或权限问题
Claude Code 没有使用预期的 Key，或该 Key 无权访问所请求的模型或端点。
- 确认 ANTHROPIC_API_KEY
- 检查 Base URL
- 检查模型权限
- 分开检查订阅登录和 API 计费
排查手册
改代码前，先收集这些事实
- 记录完整错误文本、HTTP 状态码、模型、端点和发生时间。
- 确认 Claude Code 使用的是 Anthropic 直连 Key，还是兼容网关的 Base URL。
- 把 API Key 计费与额度和 Claude Pro 或 Max 订阅状态分开检查。
- 遇到 429 时，先降低并发和上下文长度，再考虑切换供应商。
- 遇到 500 或 529 时，退避重试一次，再对比其他路由或备用模型。
- 使用网关时，先核对 Messages 兼容端点、模型路由、缓存行为和支持页面。
Pro 或 Max 不等于 API 计费
检查实际使用的 Key、Base URL 和计费来源，不要假设订阅套餐与 API 额度共用同一余额。
获取 API 访问使用网关？先核对 Messages 端点
Claude Code 类客户端通常需要 Messages 兼容端点、有效的 API Key，以及支持当前工作负载的模型路由。
查看文档常见问题
Claude Code API 错误
为什么 Claude Code 提示达到速率限制？
账号、工作区、模型或路由发送的请求数或 Token 数超过限制。 降低并行 Agent 数 · 缩短上下文 · 退避后重试 · 检查当前额度和模型限制
Claude Pro 或 Max 包含 API Key 吗？
检查实际使用的 Key、Base URL 和计费来源，不要假设订阅套餐与 API 额度共用同一余额。
遇到 API 500 错误该怎么办？
供应商或路由返回服务端故障。一次重试可能恢复；持续失败需要核对路由证据。 记录 request id · 只重试一次 · 重复失败时切换路由 · 不要先改写提示词
529 过载是什么意思？
上游服务负载过高，通常更换 API Key 无法解决。 执行退避 · 使用备用模型 · 减小请求体 · 检查支持或状态频道
资料来源
去哪里核对当前规则
最终限额和错误含义以官方文档为准；社区讨论只用于判断需求，不作为事实来源。