运行时错误速查手册

Claude Code 在 CLI、Desktop App 和 Web 上共享同一套运行时错误体系。安装和登录错误见 配置诊断速查。

一、错误消息索引

二、服务端错误

来自 Anthropic 基础设施，与账户或请求无关。

API Error: 500 Internal server error

API 内部异常。排查步骤：

1. 检查 status.claude.com 是否有活跃事件
2. 等待约 1 分钟后重发消息（输入 try again 即可，无需重新粘贴）
3. 持续出现时运行 /feedback 提交诊断

API Error: Repeated 529 Overloaded errors

API 全局容量不足。529 不计入用量配额。排查步骤：

1. 检查 status.claude.com
2. 等待几分钟
3. 运行 /model 切换到其他模型继续工作（容量按模型独立计算）

Request timed out

API 在超时截止时间前未响应（默认 10 分钟）。排查步骤：

1. 重试请求
2. 拆分为更小的提示
3. 慢网络/代理场景提高 API_TIMEOUT_MS

Auto mode 安全分类器不可用

Auto mode 用于分类操作安全性的模型过载。读取、搜索和工作目录内编辑跳过分类器，不受影响。

等待几秒后重试。Claude 通常会自动重试。

三、用量限制错误

与账户或计划配额相关，不同于服务端错误。

You've hit your session/weekly/Opus limit

滚动配额用尽。排查步骤：

1. 等待消息中显示的重置时间
2. /usage 查看限额和重置时间
3. /extra-usage 购买额外用量（Pro/Max 可用；Team/Enterprise 向管理员申请）
4. 在 claude.com/pricing 升级计划

Server is temporarily limiting requests

短期限流，与计划配额无关。已自动重试过。等待后重试。

Request rejected (429)

API key / Bedrock / Vertex AI 项目的速率限制。排查步骤：

1. /status 确认活跃凭据正确（环境中的 ANTHROPIC_API_KEY 可能覆盖订阅）
2. 在 provider 控制台检查限额
3. 降低并发：减小 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY、减少并行 subagent、用 /model 切换更小模型

Credit balance is too low

Console 组织预付积分用尽。在 platform.claude.com/settings/billing 充值或启用自动续费。也可用 /login 切换到订阅认证。

四、鉴权与权限错误

Not logged in

无有效凭据。运行 /login 认证。使用 API key 时确认 ANTHROPIC_API_KEY 已 export。CI 场景配置 apiKeyHelper 脚本。

Invalid API key

API key 被拒绝。排查步骤：

1. 检查 key 是否已撤销（Console）
2. env | grep ANTHROPIC 检查环境中是否有过期 key
3. 卸载 key 后用 /login 切换到订阅认证
4. /status 确认实际使用的凭据来源

This organization has been disabled

来自已禁用 Console 组织的 API key 覆盖了订阅登录。卸载 ANTHROPIC_API_KEY 并重启。

OAuth token revoked / expired

保存的登录凭据失效。运行 /login 重新认证。重复出现时先 /logout 再 /login。

OAuth scope requirement

CopyOAuth token does not meet scope requirement: user:profile

Token 早于某个功能所需的权限范围。运行 /login 获取新 token。

五、网络错误

Claude Code 无法连接到 API，通常是本地网络、代理或防火墙问题。

Unable to connect to API

TCP 连接失败。排查步骤：

1. curl -I https://api.anthropic.com 确认网络可达
2. 企业代理场景设置 HTTPS_PROXY
3. LLM 网关场景设置 ANTHROPIC_BASE_URL
4. 检查防火墙允许列表

curl 成功但 Claude Code 失败时：检查 /etc/resolv.conf（Linux/WSL）、残留 VPN tunnel（macOS）、Docker Desktop 流量拦截。

SSL certificate verification failed

代理或安全设备用自签证书拦截 TLS。设置 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem。不要使用 NODE_TLS_REJECT_UNAUTHORIZED=0。

六、请求体错误

API 收到请求但拒绝其内容。

Prompt is too long

对话加附件超出模型上下文窗口。排查步骤：

1. /compact 压缩或 /clear 清空
2. /context 查看各类消耗占比
3. /mcp disable + 服务器名 禁用不用的 MCP 服务器
4. 精简 CLAUDE.md 或使用路径条件规则

Error during compaction: Conversation too long

/compact 本身因窗口已满而失败。按 Esc 两次后退几轮再 /compact，或 /clear 重新开始。

Request too large

原始请求体超出 API 字节限制（最大 30 MB）。按路径引用大文件而非粘贴内容。

Image / PDF 错误

Extra inputs are not permitted

代理或 LLM 网关剥离了 anthropic-beta 请求头。配置网关转发该头。回退方案：CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。

There's an issue with the selected model

模型名未识别或账户无权限。用 /model 选择可用模型。使用 sonnet/opus 别名而非完整版本 ID。

thinking.type.enabled is not supported

Claude Code 版本过旧。运行 claude update 升级到 v2.1.111+。

Thinking budget exceeds output limit

MAX_THINKING_TOKENS 设置高于 provider 输出限制。降低 MAX_THINKING_TOKENS 或提高 CLAUDE_CODE_MAX_OUTPUT_TOKENS。

Tool use or thinking block mismatch

对话历史中 tool_use/tool_result/thinking 块序列不一致。运行 /rewind 或按 Esc 两次回退到正常检查点。

七、响应质量问题

回复质量下降但无报错时，按以下顺序排查：

八、自动重试与排查环境变量

Claude Code 在显示错误前自动重试瞬态故障（500、529、超时、429、断连），最多 10 次指数退避。重试期间 spinner 显示 Retrying in Ns · attempt x/y。

相关速查手册: 配置诊断速查 | 斜杠命令速查 | CLI 参数速查