错误参考

查 Claude Code 运行时错误的含义与恢复方法。

是什么

本页列出 Claude Code 在运行时显示的错误信息，说明每条错误的含义及如何恢复，并涵盖无报错但响应质量异常时该检查什么。这些错误与恢复命令在 CLI、Desktop app 和 Claude Code on the web 三个界面通用，因为它们都封装同一个 Claude Code CLI。

安装阶段的错误（如 command not found、TLS 失败）不在此页，见 Troubleshoot install。由于 Claude Code 调用 Claude API 获取模型响应，大多数运行时错误对应底层 API 错误码；本页讲的是这些错误在 Claude Code 内部的含义与恢复方式。

怎么工作

按终端里看到的错误信息，匹配页面顶部 Find your error 表格中的对应章节
错误分六大类：Server errors（服务端）、Usage limits（用量上限）、Authentication（鉴权）、Network（网络连接）、Request errors（请求内容被拒）、Response quality（响应质量）
瞬时失败（5xx、529、超时、临时 429、断连）会自动重试，最多 10 次并指数退避；重试期间显示 Retrying in Ns · attempt x/y 倒计时。看到本页错误说明重试已耗尽
可用 CLAUDE_CODE_MAX_RETRIES（默认 10）和 API_TIMEOUT_MS（默认 600000 毫秒，即 10 分钟）两个环境变量调整重试与超时行为
随时运行 /status 查看当前生效的凭据；环境变量（如 ANTHROPIC_API_KEY）优先级高于 /login
响应变差但无报错时，先用 /model、/effort、/context、/doctor 排查模型选择、effort 等级、上下文压力与陈旧指令
错误未列出或修复无效时：运行 /feedback 发送 transcript，/doctor 检查本地配置，查 status.claude.com 看事件，或搜 GitHub issues

怎么配置 / 用法

text

# 排错常用命令
/status      # 查看当前生效凭据与活跃模型
/login       # 重新登录鉴权
/logout      # 彻底清除已存 token（再 /login）
/usage       # 查看套餐用量上限与重置时间
/model       # 切换/选择可用模型
/compact     # 压缩对话以释放上下文
/clear       # 清空当前会话重新开始
/context     # 查看上下文窗口占用明细
/rewind      # 回退到损坏轮次前的检查点
/doctor      # 检查本地配置问题
/feedback    # 发送 transcript 给 Anthropic
claude --debug   # 查看 auto mode 分类器等底层调试日志
claude update    # 升级 CLI（如 Opus 4.7/4.8 版本不匹配）
curl -I https://api.anthropic.com   # 验证能否连到 API 主机

什么时候用

终端出现明确报错信息，需要查含义与恢复步骤时
无报错但感觉响应质量低于平常，需要排查会话状态时
跨 CLI / Desktop / web 三个界面遇到同类运行时错误时
脚本或 CI 中想通过调环境变量控制重试与超时行为时

限制 / 坑

仅覆盖来自 Claude API 的运行时错误；安装错误、MCP 连接、hook 失败、权限/文件系统错误各有专页
原始 HTTP 状态码定义见 Claude Platform error reference，本页不重复
部分错误界面相关（如 host_not_allowed 只在 cloud/routine 会话出现），本地 CLI 不受该网络策略影响

硬事实速查（24 条）

API Error: 500 Internal server error：API 内部意外失败，与你的 prompt/设置/账户无关；查 status.claude.com，稍等后重发（可直接输 try again），持续则 /feedback
API Error: Repeated 529 Overloaded errors：API 全员临时满载，不计入配额；稍等重试，或 /model 换模型（容量按模型计）
Request timed out：API 在连接截止前未响应，默认超时 10 分钟；重试、拆小 prompt，慢网络/代理可调高 API_TIMEOUT_MS
auto mode 无法判定动作安全性：工作目录内的读/搜/改不走分类器仍可用；稍等重试，或 claude --debug 看详情，或 /compact 缩小对话；非交互模式下 transcript 超限会中止
You've hit your session/weekly/Opus limit：套餐滚动用量耗尽，到所示重置时间前被阻断；等待重置、/usage 查上限、/usage-credits 购买额外用量
Request rejected (429)：触达 API key 或 Bedrock/Vertex 项目配置的速率上限；/status 确认凭据，到 provider 控制台提额，或降 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY
Credit balance is too low：Console 组织预付额度用尽；到 platform.claude.com/settings/billing 充值（可开 auto-reload），或 /login 切订阅鉴权
Not logged in · Please run /login：本会话无有效凭据；运行 /login，或确认 ANTHROPIC_API_KEY 已 export，CI 可配 apiKeyHelper
Invalid API key · Fix external API key：环境变量或 apiKeyHelper 返回的 key 被 API 拒绝；查拼写/吊销、env | grep ANTHROPIC 找陈旧 .env key，或 unset 后 /login
This organization has been disabled：来自被停用 Console 组织的陈旧 ANTHROPIC_API_KEY 覆盖了订阅登录；unset 该变量并从 shell profile 移除后重启
Your organization has disabled Claude subscription access：组织服务端设置禁止订阅登录，本地无法覆盖；请管理员开放，或改用 Console API key
Routines are disabled by your organization's policy：Team/Enterprise 管理员在组织级关闭了 routines；请管理员在 admin-settings 开启 Routines 开关
OAuth token revoked / has expired：已存登录失效；/login 重登，同会话内仍报错则先 /logout 再 /login
OAuth token does not meet scope requirement: user:profile：已存 token 早于新功能所需权限 scope（常见于 /usage、状态栏用量）；/login 重铸新 token
Unable to connect to API（ECONNREFUSED/ECONNRESET/ETIMEDOUT/fetch failed）：TCP 连接失败，多为无网络、VPN 阻断或企业代理未配；curl -I https://api.anthropic.com 验证，配 HTTPS_PROXY 或 ANTHROPIC_BASE_URL
SSL certificate verification failed / Self-signed certificate detected：网络上的代理用自有证书拦 TLS 而 Claude Code 不信任；用 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem 指向 CA bundle，切勿设 NODE_TLS_REJECT_UNAUTHORIZED=0
HTTP 403 + x-deny-reason: host_not_allowed：cloud 会话/routine 的出站请求被环境网络策略拦；在 cloud 环境设置里把 Network access 从 Trusted 改 Custom 并加白名单域名，本地 CLI 不受影响
Prompt is too long：对话加附件超出模型上下文窗口；/compact 或 /clear，/context 看占用，/mcp disable <name> 移除未用工具，精简 CLAUDE.md
Error during compaction: Conversation too long：/compact 因无足够空间放摘要而失败；按两次 Esc 回退几轮再 /compact，不够则 /clear
Request too large (max 30 MB)：原始请求体在分词前超字节上限，多因粘贴大文件；按两次 Esc 回退该轮，改用路径引用大文件
There's an issue with the selected model：模型名未识别或账户无权限；/model 重选，用 sonnet/opus 别名，按优先级排查 --model、ANTHROPIC_MODEL、各级 settings 中的陈旧 ID
thinking.type.enabled is not supported for this model：CLI 版本低于 Opus 4.7/4.8 最低要求；claude update 重启（4.7 需 v2.1.111+，4.8 需 v2.1.154+），或 /model 选 Opus 4.6/Sonnet
Usage Policy refusal：对话内容触发 Usage Policy 检查被拒，消息含可向支持引用的 Request ID；两次 Esc 或 /rewind 回退后换措辞，认不出则 /clear
Responses seem lower quality than usual（无报错）：通常是会话状态而非模型本身；/model 确认模型、/effort 看 effort 等级、/context 看上下文压力、/doctor 查陈旧 CLAUDE.md，回退重述优于在原线程纠正

官方出处：https://code.claude.com/docs/en/errors

错误参考 ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​