Claude Code 运行时错误的查阅手册。每类错误对应底层 Claude API 的 HTTP 状态码，本文说明在 Claude Code 中的含义和恢复方法。
核心机制
自动重试：服务器错误、过载、超时、临时 429 和连接断开都会自动重试最多 10 次（指数退避）。看到错误时，重试已经耗尽。
重试调优：
CLAUDE_CODE_MAX_RETRIES（默认 10）：降低可让脚本更快失败API_TIMEOUT_MS（默认 600000）：慢网络或代理时需要提高
错误分类速查
服务器错误
| 错误 | 含义 | 处理 |
|---|---|---|
API Error: 500 Internal server error | API 内部故障，非用户问题 | 查 status.claude.com，重试，持续则 /feedback |
API Error: Repeated 529 Overloaded errors | API 容量不足（非配额问题） | 等几分钟，/model 切换到其他模型 |
Request timed out | 连接超时 | 重试，分解大任务，提高 API_TIMEOUT_MS |
使用限制
| 错误 | 含义 | 处理 |
|---|---|---|
You've hit your session/weekly limit | 订阅配额耗尽 | 等重置时间，/usage 查看，/extra-usage 购买额外用量 |
Request rejected (429) | API key 速率限制 | 检查 /status 确认使用的凭证，降低并发 |
Credit balance is too low | Console 预付费余额不足 | 充值或切换到订阅认证 |
认证错误
| 错误 | 含义 | 处理 |
|---|---|---|
Not logged in · Please run /login | 无有效凭证 | /login 重新认证 |
Invalid API key | API key 无效或已撤销 | 检查 key，unset ANTHROPIC_API_KEY 后用订阅认证 |
This organization has been disabled | 旧 API key 覆盖了订阅认证 | unset ANTHROPIC_API_KEY，从 shell profile 中删除 |
OAuth token revoked/expired | 登录令牌失效 | /logout 后 /login |
网络错误
| 错误 | 含义 | 处理 |
|---|---|---|
Unable to connect to API | TCP 连接失败 | 检查网络，配置 HTTPS_PROXY，确认防火墙规则 |
SSL certificate verification failed | TLS 证书不受信任（企业代理） | 设置 NODE_EXTRA_CA_CERTS 指向 CA bundle |
403 + x-deny-reason: host_not_allowed | 云会话网络策略阻止 | 在云环境设置中添加允许域名 |
请求错误
| 错误 | 含义 | 处理 |
|---|---|---|
Prompt is too long | 超出上下文窗口 | /compact 压缩，/context 查看占用，禁用不用的 MCP |
Error during compaction: Conversation too long | 压缩本身也失败 | Esc+Esc 回退几条消息后再 /compact |
Request too large (max 30 MB) | HTTP 请求体超限 | Esc+Esc 回退，改用路径引用大文件 |
Extra inputs are not permitted | 代理/网关丢弃了 anthropic-beta 头 | 配置网关转发该头，或设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 |
thinking.type.enabled is not supported | Claude Code 版本过旧 | claude update 升级到 v2.1.111+ |
响应质量下降（无错误）
不是错误但响应质量异常时，按顺序检查：
/model确认当前模型是否符合预期/effort检查推理深度，复杂任务需要提高/context查看上下文占用，接近上限时质量下降/doctor检查 CLAUDE.md 是否过大或过时
关键原则：遇到错误回复时，用 Esc+Esc 回滚比在对话中纠错更有效，避免错误答案锚定后续回复。
与其他概念的关联
- troubleshoot-install — 安装和登录阶段的错误
- troubleshooting — 性能、稳定性、搜索问题
- env-vars —
API_TIMEOUT_MS、CLAUDE_CODE_MAX_RETRIES调优重试行为
实践要点
- 529 过载不计入配额，切换模型是最快的解决方案
ANTHROPIC_API_KEY环境变量优先级高于订阅认证，旧 key 残留是常见问题根源- 企业代理环境中
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1可解决大多数 400 错误 /feedback提交时会附带会话记录，是最快让 Anthropic 诊断问题的方式