12.2 API 调用异常排查
服务器错误（5xx）
服务器端问题，影响所有用户，非账号特定：
| 错误 | 原因 | 解决方案 |
|---|
| API Error: 500 | Anthropic 基础设施故障 | 查看 status.claude.com，等待恢复后重试 |
| API Error: 529 Overloaded | API 负载过高 | 几分钟后重试，或切换模型 /model sonnet |
| Request timed out | 请求超过 10 分钟限制 | 减少提示词长度，将大文件分批处理 |
额度限制错误
| 错误 | 原因 | 解决方案 |
|---|
| You've hit your session limit | 超出计划用量额度 | 等待额度重置，升级订阅，或使用额外用量 |
| Server is temporarily limiting requests | 临时限流 | 短暂等待后重试 |
| Request rejected (429) | API Key 触发了速率限制 | 检查 API Console 的用量限制 |
| Credit balance is too low | Console 余额不足 | 在 Console 中充值 |
认证错误
| 错误 | 原因 | 解决方案 |
|---|
| Not logged in | 无有效登录凭据 | 运行 /login 或设置 API Key |
| Invalid API key | API Key 错误或已禁用 | 在 Console 检查 Key 状态，重新生成 |
| Organization disabled | 团队账户被暂停 | 联系团队管理员 |
| OAuth token revoked | 登录 Token 过期 | /logout 后重新 /login |
请求错误
| 错误 | 原因 | 解决方案 |
|---|
| Prompt is too long | 超出模型上下文限制 | 减少提示词，或使用 /compact 压缩上下文 |
| Conversation too long | 上下文历史超出限制 | /clear 开始新会话 |
| Request too large | Token 预算超限 | 使用 /compact 压缩 |
| Image was too large | 图片超过 10MB | 压缩图片后再发送 |
| PDF too large / password protected | PDF 文件过大或加密 | 压缩 PDF 或移除密码 |
自动重试机制
Claude Code 会对以下错误自动进行指数退避重试（最多 10 次）：
- 5xx 服务器错误
- 529 Overloaded
- Request timed out
- 临时性的 429 限流
自定义重试和超时
export API_TIMEOUT_MS=600000 # 单次请求超时（默认 10 分钟）
export CLAUDE_CODE_MAX_RETRIES=10 # 最大重试次数（默认 10）
诊断步骤
遇到 API 错误时，按以下步骤排查：
- 查看错误信息的具体类型（对照上方表格）
- 运行
/doctor 检查配置状态
- 运行
/usage 查看当前用量
- 如果是 5xx，查看 status.claude.com 确认是否为已知故障
- 尝试切换模型：
/model haiku（更少限流）
- 如果是认证错误，重新登录：
/logout → /login