我做过一个不严谨的统计：在我们团队几个开发交流群里，每周出现频率最高的求助，前三名全是 Claude Code 的报错问题。

而且每次都是同样的几个错误。

401 Unauthorized、Rate limit exceeded、Context length exceeded……这些报错不复杂，但每次出现，都能让刚上手的人卡半天——因为报错信息本身说的是英文，而且通常不会直接告诉你根本原因在哪。

我自己也在这些坑里趟过。这篇文章是我的踩坑记录，按"我遇到这个报错时需要知道什么"来组织，不是 API 文档的翻译版。

错误 1：401 Unauthorized

报错场景： 刚安装完 Claude Code，第一次使用，或者某天突然不能用了。

报错原因有三种，按可能性排序：

最常见：API Key 没有正确配置

检查 Key 有没有配进去：

echo $ANTHROPIC_API_KEY

如果输出为空，说明环境变量没设置。在 ~/.zshrc 或 ~/.bashrc 里加上：

export ANTHROPIC_API_KEY=sk-ant-api03-你的key

然后 source ~/.zshrc 使其生效。

次常见：Key 格式不对

新版 Key 的格式是 sk-ant-api03-xxx，如果你的 Key 是老格式 sk-ant-xxx，在某些功能上会报 401。去 Anthropic Console 删掉旧 Key，重新创建一个新格式的。

偶尔出现：Key 被撤销了

如果你的账号检测到异常使用（比如 Key 泄漏被滥用），Anthropic 会自动撤销 Key。去 Console 看一下 Key 的状态，红色标记的就是被撤销的。

错误 2：429 Rate Limit Exceeded

报错场景： 正在愉快地写代码，突然 Claude 停止响应，报这个错。

说人话就是： 你请求太频繁了，触发了限流。

两种情况，解法不同：

情况一：短时间内请求太多（每分钟超限）

通常是因为你在运行批处理脚本，短时间内并行发了太多请求。

解法：在脚本里加请求间隔：

# 每次请求之间等待 2 秒
find app/api -name "route.ts" | while read file; do
  claude -p "..." < "$file"
  sleep 2
done

情况二：每月总用量超出了免费额度

免费账号每月 $5 额度用完之后，就会持续报 429，不是请求太快，是额度归零了。

检查方式：去 console.anthropic.com/usage 看当月用量。如果已经归零，要么等下月重置，要么充值。

大多数教程不告诉你的细节： 429 有两种子类型——rate_limit_error 是频率限制，等一会儿会自动恢复；insufficient_quota 是额度耗尽，等多久都没用，必须充值。两种报错消息看起来很像，但处理方式完全不同。

错误 3：400 Bad Request - context_length_exceeded

报错场景： 项目文件加了很多，或者对话进行了很长时间，突然报这个错。

根本原因： 上下文窗口超出了 200k tokens 的上限。

解法分三步：

第一步：立即清理上下文

按 Cmd+Shift+P → Claude: Clear Context，清掉所有加载的文件，重新开始。

第二步：配置 .claudeignore 防止重犯

node_modules/
.next/
dist/
*.d.ts
!src/types/*.d.ts
package-lock.json

第三步：如果是对话历史太长

开新 Session，用摘要接力的方式延续上下文（上一篇"记忆机制"文章里详细讲过）。

错误 4：Connection Error / Network Error

报错场景： Claude Code 完全无法响应，或者时好时坏。

检查顺序：

第一步：验证网络是否能访问 Anthropic API

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

如果超时或者报连接错误，是网络问题，不是 Claude Code 的问题。

第二步（国内用户）：检查代理是否正确配置

echo $https_proxy
echo $http_proxy

如果输出为空，代理没有配进终端环境变量。在 ~/.zshrc 加：

export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890

端口号替换成你实际的代理端口。

第三步：检查 Anthropic 服务状态

访问 status.anthropic.com，看是不是 Anthropic 那边的服务出问题了。这种情况不常见，但真实发生过——有一次我以为是自己网络问题，折腾了一小时，最后发现是 Anthropic 的 API 服务在做维护。

错误 5：Model not available / Model does not exist

报错场景： 在 CLI 里指定模型名称，或者在设置里选模型，报模型不存在。

最常见原因：模型名称字符串写错了

Anthropic 的模型名称有严格的格式，一个字符都不能错：

# 正确的模型名称（2025年）
claude-opus-4-6
claude-sonnet-4-6
claude-haiku-4-5-20251001

# 错误的写法（这些都会报错）
claude-3-opus          # 老格式
claude-opus            # 缺少版本号
Claude-Sonnet-4.6      # 大写了 C，用了点号

说人话就是： 去 docs.anthropic.com/models 复制准确的模型字符串，不要手打，不要凭记忆写。

另一种原因：你的账号没有该模型的访问权限

Opus 系列对部分账号有访问限制。如果你的免费账号报 Opus 模型不可用，需要先完成付费升级。

错误 6：Invalid API Key format

报错场景： 配置了 Key，但报格式无效。

三个检查点：

# 检查 Key 有没有多余的空格
echo "$ANTHROPIC_API_KEY" | cat -A
# 如果行尾有 ^ 字符，说明有换行符或空格，需要清掉

最常见的导致格式错误的操作：

• 从 PDF 或网页复制 Key 时，带入了不可见字符

• 在配置文件里，Key 前后加了引号（export ANTHROPIC_API_KEY="sk-ant-..." 这样的引号有时会导致问题）

• 从截图用 OCR 识别出来的 Key，有字符被识别错

干净的配置方式： 去 Anthropic Console 点"复制"按钮，直接粘贴，不要手打，不要中转。

错误 7：Permission denied 相关错误

报错场景： Claude Code 想读取或修改某个文件，被拒绝了。

原因一：文件权限问题

# 检查文件权限
ls -la 报错的文件路径

# 修复权限
chmod 644 文件名  # 普通文件
chmod 755 目录名  # 目录

原因二：Claude Code 的 Permission 设置拒绝了该操作

你之前设置了"总是拒绝"某类操作，现在需要这个操作，但它被挡住了。

解法：按 Cmd+Shift+P → Claude: Manage Permissions，找到对应的规则，修改为"询问"或"允许"。

原因三：.claudeignore 把该文件排除了

检查 .claudeignore 里有没有误匹配到这个文件的规则。用 cat .claudeignore 逐行检查。

错误 8：Overloaded / Service Temporarily Unavailable

报错场景： 不是自己的问题，是 Anthropic 服务器压力大。

这个错误你什么都做不了，只能等。

判断是暂时性还是持续性：

• 等 1-2 分钟后重试，如果恢复了，是临时过载

• 持续 10 分钟以上，去 status.anthropic.com 确认是否有服务事故

一个应急方案： 如果你赶时间，这时候可以切换到通义千问的 API（前面安装篇讲过配置方式），不用等 Anthropic 恢复。这也是为什么我建议同时配两套 API——主备互为冗余。

错误 9：File too large / Max tokens exceeded for single message

报错场景： 试图让 Claude 分析一个大文件，或者一次发送了很多内容。

根本原因： 单次消息的 token 数超过了限制。

解法：拆分文件，分段处理

# 把大文件分成 200 行一段
split -l 200 大文件.ts 分段_

# 逐段处理
for segment in 分段_*; do
  echo "处理: $segment"
  claude -p "分析这段代码的类型安全性" < "$segment"
done

更聪明的做法： 不要让 Claude 读整个大文件，而是精准定位你需要它分析的部分：

# 只提取你关心的函数（第 150-220 行）
sed -n '150,220p' 大文件.ts | claude -p "分析这个函数的性能问题"

错误 10：Claude 生成代码后报 TypeScript 错误，但 Claude 坚持说代码没问题

这个不是 Claude Code 的网络报错，是使用过程中最让人抓狂的"隐性错误"——Claude 给你的代码有 TypeScript 类型错误，但它告诉你"代码是正确的"。

根本原因： Claude 在对话里"看到"的是它自己生成的代码，但它不一定知道你项目里的实际类型定义。它判断"正确"的依据是通用的 TypeScript 知识，不是你项目的具体类型系统。

解法：把报错信息和类型文件一起喂给它

这段代码报了以下 TypeScript 错误：

Type 'string | null' is not assignable to type 'string'

错误在第 23 行。我的 User 类型定义如下： （粘贴 types/user.ts 的内容） 请根据实际类型定义修复这个错误。

说人话就是： 不要只把报错粘给它，要把"报错 + 相关类型定义"一起给。它只有看到你的类型系统，才能真正修复类型错误，而不是给你一个"绕过类型检查"的修法。

踩坑补充：两个让我浪费时间最多的错误

坑一：429 报错，花了一小时以为是 Key 的问题

有一次用 CLI 批处理脚本，跑到一半开始大量报 429。我以为是 Key 有问题，把 Key 删了重新生成，重新配，还是报 429。

折腾了一个小时，最后去 Console 看了一眼用量，才发现当月免费额度已经用完了。

教训： 遇到 429，第一步先去 Console 看用量，不要瞎折腾 Key。

坑二：TypeScript 错误反复修反复出，循环了七八轮

让 Claude 修一个类型错误，它改了，新的类型错误出来了，再让它改，又出了另一个。循环了七八轮，问题越来越多。

原因： 我每次只把新的报错给它，没有给类型定义文件。它每次都在用"通用 TypeScript 知识"修错，没有真正理解我项目的类型系统。

解法： 第一轮就把 types/ 目录下的相关文件 Add to Context，之后所有的类型修复都在这个上下文里进行，问题从七八轮降到了一两轮。

报错不可怕，怕的是不知道从哪里查。

把这篇文章存起来，下次遇到报错，先对照这里的检查顺序走一遍，90% 的常见报错不需要去 Stack Overflow。

---

报错速查表

错误信息                          第一步检查
─────────────────────────────────────────────────
401 Unauthorized                  API Key 是否正确配置
429 Rate Limit Exceeded           Console 查当月用量 / 降低请求频率
400 context_length_exceeded       Clear Context / 配置 .claudeignore
Connection Error                  curl 测试网络 / 检查代理配置
Model not available               复制准确模型名 / 检查账号权限
Invalid API Key format            检查 Key 是否有多余空格或特殊字符
Permission denied                 检查文件权限 / Permission 设置
Overloaded                        等待重试 / 切备用 API
File too large                    分段处理 / 精准截取需要的部分
TypeScript 错误反复               带上类型定义文件一起喂给 Claude
─────────────────────────────────────────────────

---

你遇到的最离谱的 Claude Code 报错是什么？

不是常见的那种，是那种排查了很久、最后发现原因让你哭笑不得的那种。