Claude Code 报错速查：官方 errors 页把错误分成了哪几类

2026-08-18

终端里蹦出一行英文，第一反应通常是把整句话复制去搜。这个动作经常白费，因为官方那句报错里往往带着变量：模型名、错误码、文件路径、次数计数，整句去搜是搜不到的。

Claude Code 官方文档有一页 Error reference（code.claude.com/docs/en/errors），开头就是一张 Find your error 索引表，左列是你会看到的消息模板，右列是它归属的小节。用法是拿消息里不变的那一段去匹配，而不是整句。

本文只做一件事：把这一页的分类结构讲清楚，以及每一类的第一步该做什么。单条报错（API Error: 500 Internal server error、重复的 529 Overloaded、Request rejected (429) 之类）各有专门篇目在讲，这里不重复。

先确认你翻的是不是这一页

官方文档把「出问题了」分散在好几页上，走错页会白翻半天。判定动作很简单，看问题发生在什么阶段：

claude 根本起不来、command not found、PATH 不对、安装期的 TLS 失败、登录循环、403 Forbidden、云厂商凭据 —— 去 Troubleshoot installation and login 那一页
起来了但是卡、吃内存、搜不到文件、终端里字是花的 —— 去 Troubleshooting 页的 Performance and stability 一节
设置不生效、hooks 不触发、MCP 服务器加载不上 —— 去 Debug your configuration 那一页
会话跑起来之后弹出的运行时报错 —— 才是 Error reference 这一页

这张路由表是 Troubleshooting 页开头自己列的。它还写明：拿不准就在会话里跑 /doctor 自检，claude 压根启动不了就在 shell 里跑 claude doctor。

另有一条容易漏掉的适用范围说明：除了 Wrapper and IDE errors 那一节（那些消息由启动 Claude Code 的程序打印），页上的错误与恢复命令在 CLI、桌面端、Claude Code on the web 三个端通用，因为三者包的是同一个 CLI。

这一页的分类骨架

Error reference 的顶层小节里，除去索引表、Automatic retries 和 Report an error 这三节，剩下 15 个小节就是它的分类：11 类是报错，3 类是警告，还有 1 类是「没有报错但结果不对」。

分类小节	大致含义	第一步
Server errors	推理服务端返回的失败	看状态页，隔一会儿重发
Usage limits	账号或套餐侧的额度与节流	跑 `/usage`、`/status`
Authentication errors	无法向 API 证明你是谁	跑 `/status` 看当前生效的是哪个凭据
Network and connection errors	请求没到目的地，或回程被改写	用 `curl` 单独探一次 API 主机
Request errors	请求内容本身被拒	跑 `/context` 看窗口占用
Installation errors	安装与更新阶段	重跑安装或 `claude update`
Command-line errors	`claude` 命令与子命令	核对参数组合与配置文件
Plugin errors	`plugin` 与 marketplace 配置	按消息点名的组件改配置
Tool errors	内置工具报出来的	多数 Claude 自己会纠正
Background session errors	后台会话没有自己的交互终端	附着到会话上再跑一次
Wrapper and IDE errors	启动 Claude Code 的那个程序报的	去看那个程序自己的日志
Rewind warnings	`/rewind` 恢复时跳过了某些路径	找出被跳过的是哪几个文件
Session saving warnings	转录没在存盘	按错误码修盘/权限
Configuration warnings	读到了但没生效的配置	按警告点名的来源改
Responses seem lower quality than usual	没报错但结果变差	依次查模型、effort、上下文、旧指令

这张表不是拿来背的，是拿来分流的：先判断故障在服务端、账号侧、网络路上、还是你本机的配置与命令，剩下的三类警告根本不是报错。

先看它是不是已经替你重试过了

Automatic retries 一节写明，页上这些错误显示出来时，Claude Code 已经做完了适用于该失败的重试。

判定动作：看重试期间的倒计时标签。文档写明重试时会给出 Retrying in Ns · attempt x/y 形式的倒计时，前面带原因标签；对于你能马上处理的失败（网络断了、TLS 握手失败、命中限流），标签从第一次尝试就点名原因，其它错误先显示为 API error。另有一条要分清：Waiting for API response · will retry in … · check your network 出现时请求还没有失败，倒计时跑到的是「放弃这条卡住的连接」那个点。

哪些重试、哪些不重试，是分类的一条硬依据：

会重试：响应还没开始流式返回时的服务端错误、过载、请求超时；中途断掉的连接；检测到电脑休眠导致的断连；卡住的响应流；临时性的 429 节流
不重试：TLS 证书校验失败（文档自述是为了让你立刻去修证书配置）；在 Claude 已经完成一段文本或一次工具调用之后才到达的失败（重发会把同样的工具调用跑第二遍，所以保留已完成的部分并附上「响应可能不完整」的提示）；响应已经结束之后才到的失败
网关的花费上限 429 不算节流：文档写明这类响应被标了 x-should-retry: false，所以不重试，直接显示

想调重试行为，文档给的是三个环境变量：CLAUDE_CODE_MAX_RETRIES、CLAUDE_CODE_RETRY_WATCHDOG（文档说明用于 CI 这类无人值守场景）、API_TIMEOUT_MS。默认值与上限随版本变动，以官方 env-vars 页为准。

最容易分错的三组

服务端 vs 用量。 这两类消息里都可能出现 429。文档给的区分依据是响应头：真正的套餐限额响应带统一的配额头，而 Server is temporarily limiting requests (not your usage limit) 是服务端短时节流，靠没有那组配额头识别出来。更隐蔽的是网关花费上限，它也是 429，但既不是节流也不是你的配额用完。

用量 vs 认证。 会话/周额度是账号侧的，跑 /usage 看重置时间；认证类错误的第一步文档写得很直白：跑 /status 看当前生效的是哪个凭据。这一步能抓到一类常见误判——环境里躺着一个 ANTHROPIC_API_KEY，请求走的根本不是你以为的那条链路。

服务端 vs 网络。 判定动作是绕开 Claude Code 自己探一次：

curl -I https://api.anthropic.com

Windows 侧文档专门写了一句：在 PowerShell 里要写成 curl.exe -I https://api.anthropic.com，否则会走到内置的 Invoke-WebRequest 别名上去。

curl 探不通，往防火墙、代理（HTTPS_PROXY）、网关（ANTHROPIC_BASE_URL）方向查。curl 通了但 Claude Code 还是连不上，文档说这时问题通常在运行时和网络之间而不是网络本身，并点名三处：Linux 与 WSL 上 /etc/resolv.conf 里不可达的 nameserver、macOS 上卸载 VPN 后残留的 utun 接口与路由规则、Docker Desktop 这类容器运行时对出站流量的拦截。

Windows 侧要单独看的几条

Windows 用户会撞上几条只在这个平台出现的分支，文档里是分开写的：

查环境变量：PowerShell 里用 Get-ChildItem Env:ANTHROPIC*，对应 macOS/Linux 的 env | grep ANTHROPIC。文档提到 direnv、dotenv 插件、IDE 终端都可能从项目里的 .env 悄悄加载一个旧 key
VS Code 扩展报 Could not locate the Claude CLI on PATH：这是 Windows 上集成终端且 shell 是 PowerShell 时才有的。第一步是在 VS Code 之外新开 PowerShell 跑 where.exe claude。文档还写明两件事——PATH 要设成用户级或系统级环境变量，写在 PowerShell profile 里扩展读不到；改完必须重启 VS Code，因为扩展用的是 VS Code 启动时抓到的那份 PATH
后台会话起不来报 EUNKNOWN：文档写明这是 Windows 拒绝启动程序、错误码没有标准名称时的表现，常见触发是组策略或 AppLocker 这类软件限制策略
转录写失败的提示时机不同：文档写明 Windows 上的权限错误要在连续失败并持续一分钟以上之后才提示，理由是杀毒扫描可能让单次写入失败而重试就成功
Installation was killed before it could finish 这条消息来自 macOS/Linux 用的安装脚本（也覆盖 WSL 内的安装），Windows 原生安装脚本不会打印它
WSL 上搜索结果偏少：Troubleshooting 页写明这是跨文件系统的磁盘读性能问题，搜索仍然能用但返回的匹配比原生文件系统少，并且**claude doctor 在这种情况下 Search 一项仍显示 OK**

处置之后怎么验证

认证与凭据：回到会话跑 /status，确认生效的是你期望的那个凭据来源
安装与运行环境：在 shell 里跑 claude doctor，这是一次只读诊断；会话内则是 /doctor 自检
上下文相关：跑 /context，它会给出系统提示、工具、记忆文件、消息各占多少
拿不到细节的错误：用 claude --debug 复现一次。文档多处提到调试日志落在 ~/.claude/debug/<session-id>.txt，例如 /rewind 只报跳过了几个文件、不报路径，路径要从调试日志里取
会话存盘类警告：文档写明它在下一次写入成功时自行消失，不需要重启

什么情况说明你分错了类

这一步比前面几步都重要，因为分错类会让你在错误的方向上耗很久：

消息里带 Fix external API key，但后面跟了一段描述说这个值里有换行符——那么 API 根本没见过这个 key，请求在发出前就被拦下了。这不是 key 被吊销，去查控制台是白查
429 但你连的是网关——如果这是网关侧的花费上限，它既不是限流也不是你的配额，重试不会好转，要找网关的运维方
auto mode 拦下动作、且消息里说是「与 auto mode 无关的另一道安全检查因为更早的对话内容拦了这次请求」——文档明确写了这不是对你这个动作的判断，重试也没用，因为同样的对话内容会再次触发；换一种 permission mode 手动批准，或者开一段不含触发内容的新对话
换个模型就能继续——说明命中的是某个模型自己的容量或额度，不是账号级的会话/周额度（文档写明会话与周额度是所有模型共享的，换模型没用）
curl 能通——那就不是网络本身，按上面那三处本机方向查
报错来自 MCP 服务器连接/认证、hooks 脚本、或安装期的权限与文件系统问题——这三类 Error reference 页明说不覆盖，各有自己的页
没有任何报错，只是觉得回答变差了——这属于最后那一类，文档给的顺序是 /model、/effort、/context、再查过大或过时的 CLAUDE.md 与 MCP 工具定义。文档还写了一句反直觉的建议：这种情况下按两次 Esc 或跑 /rewind 退回到出问题那一轮之前重新提问，通常比在对话里继续纠正更有效，因为纠正会把错误的那次尝试留在上下文里

两条「文档写了不等于能用」

翻这一页时要留意两处被明确标注为不可用的情形，别当成现成能力：

claude import 文档写明可能返回 `claude import` is not yet available in this build，它由一个从服务端取回并缓存在本地的 feature flag 控制。文档列出的原因包括：装完还没起过会话所以还没取到 flag；走 Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry 等第三方 provider 时不取 flag；设置了 DISABLE_TELEMETRY、DO_NOT_TRACK、DISABLE_GROWTHBOOK、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 之一而关掉了 flag 拉取
Remote Control：文档写明它只在通过 api.anthropic.com 使用 Claude 时可用

最后一点：这一页大量条目带着「某行为自某个版本起才有」「某个版本之前是另一种表现」的注记，也就是说你搜到的那句报错文本本身也会随版本变化，用消息里不变的关键词匹配比整句更稳。该产品迭代频繁，文中涉及的命令、配置项与消息文本随版本变动，请以官方文档最新内容和 --help 的实际输出为准。

本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。