Claude Code 错误整理 — 区分 401、429、529 与安装错误

Claude Code 错误主要分为两类，而大多数搜索结果只讨论其中一类。安装和运行阶段的客户端错误，与调用模型时返回的 API 错误，在原因和解决方法上完全不同。本文重点整理后者——401、429、529——因为从订阅切换到 API 密钥后，最先遇到的通常就是这些错误。

错误字符串无论在哪个国家都会以英文显示。以下保留字符串原文，仅使用中文进行说明。

先在 30 秒内将原因分成三类

在尝试修改设置之前，先直接向端点发送一次请求。这一次请求可以区分“客户端问题 / 认证问题 / 服务器问题”。

# 오류가 클라이언트 문제인지 엔드포인트 문제인지 30초 만에 가르는 방법.
# 200이 돌아오면 키와 주소는 정상이고, 남은 문제는 Claude Code 설정입니다.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

401——不是密钥错误，而是标头错误

如果多次重新生成密钥后仍然持续出现 401，应怀疑的不是值，而是发送方式。Claude Code 会将 ANTHROPIC_AUTH_TOKEN 发送到 Authorization: Bearer 标头，并将 ANTHROPIC_API_KEY 发送到 x-api-key 标头。网关通常期待前者，因此交换两个变量后，即使密钥正常也会出现 401。

两个变量同时保留的情况也很常见。删除其中一个，重新打开 shell，然后再次尝试。变量之间的差异已整理在 ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_API_KEY 的区别中。

429——两种不同的 429

虽然数字相同，但原因完全不同。若正在使用订阅，则是触发了会话窗口限制，除了等待窗口重置外没有其他办法——此时升级到更高价位的方案也没有帮助。若正在使用 API 密钥，则是每秒请求数或令牌吞吐量限制，通过指数退避重试通常即可解决。

通过是否设置了 ANTHROPIC_BASE_URL 可以立即判断是哪一种。如果已设置，说明使用的是密钥而不是订阅。订阅限制的结构及超出限制后的选项，请参阅 Claude Code 费用。

529 overloaded_error——不是我的问题的错误

529 表示上游模型服务器暂时过载。请求内容、密钥和余额都不是原因，因此无法通过修改设置来消除这一错误。应对方式只有重试，而且指数退避的成功率远高于立即重试。

通过带有自动回退功能的网关时，如果一个上游返回 529，请求会切换到另一条路径，因此体感上的出现频率会降低。面向英语读者的详细整理请参阅 529 overloaded_error 应对。

触发订阅限制后继续工作

如果 429 来自订阅限制，可以将当前会话切换到密钥，而不必等待。无需取消订阅——只有在设置以下两个变量期间才会按密钥计费，删除后即可恢复原状。

# Claude Code를 구독 대신 API 키로 돌릴 때 쓰는 두 줄.
# 이 두 변수가 설정돼 있는 동안에는 구독 한도가 적용되지 않습니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Claude Code의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 가리키므로,
# Kunavo가 아직 제공하지 않는 모델이 호출돼 404가 나지 않도록 모델을 고정합니다.
# sonnet 별칭이 부르는 Sonnet 5.5는 Kunavo가 제공하지 않아, 고정하지 않으면
# /model sonnet, opusplan의 실행 단계, sonnet으로 지정한 서브에이전트에서 404가 납니다.
# Opus 5.5는 Claude Code v2.1.280 이상이 필요합니다(이전 버전이면 claude update로 업데이트).
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5

# haiku 별칭도 고정합니다. 고정하지 않으면 Kunavo가 제공하지 않는 모델 ID(v2.1.293부터
# Haiku 5.5)를 호출해 /model haiku와 haiku로 지정한 서브에이전트에서 404가 납니다.
# 같은 줄이 백그라운드 작업도 메인 모델 대신 Haiku로 보냅니다.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

费率会直接从目录读取：Claude Sonnet 5 每 1M 令牌为 $1.40 / $7.00，Claude Haiku 4.5 为 $0.70 / $3.50。费用从预付余额中扣除，因此没有工作的月份不会产生费用。支付方式及注册日本银行卡的方法，请参阅 Claude API 价格与支付。

安装阶段错误是另一回事

无法安装的问题大多由 Node.js 版本或全局安装权限引起，与上述三种错误不属于同一类别。先确认 claude --version 是否能正常输出。如果能输出，说明安装已完成，之后的问题属于认证或网络方面。混淆这两类问题会耗费最多时间。

常见问题