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 金鑰，表示每秒請求數或 Token 處理量受到限制，透過指數退避重試通常即可解決。

可透過是否設定 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

# 백그라운드 작업을 가장 싼 모델로 보내는 한 줄 — 매 세션 효과가 있습니다.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

費率會直接從目錄讀取：Claude Sonnet 5 每 1M Token 為 $1.40 / $7.00，Claude Haiku 4.5 為 $0.70 / $3.50。費用會從預付餘額扣除，因此未工作的月份不會產生費用。付款方式與日本國內信用卡的登錄方法整理於 Claude API 價格與付款。

安裝階段錯誤是另一回事

無法安裝的問題大多是 Node.js 版本或全域安裝權限造成，與上述三種錯誤屬於不同系統。請先確認 claude --version 是否能正常輸出。如果能輸出，就表示安裝已完成；後續問題屬於驗證或網路層面。混淆這兩類問題會浪費最多時間。

常見問題