Claude Codeのエラー整理 — 401・429・529とインストールエラーの見分け方

Claude Codeのエラーは大きく2種類に分かれ、検索結果の大半はその一方しか扱っていません。インストール・実行段階のクライアントエラーと、モデル呼び出し時に返されるAPIエラーでは、原因も解決方法もまったく異なります。この記事では後者、つまり401、429、529を中心に整理します。サブスクリプションからAPIキーへ移行した直後に最初に遭遇しやすいエラーだからです。

エラー文字列はどの国でも英語で表示されます。以下では文字列を原文のまま示し、説明だけを日本語で記載します。

まず30秒で原因を3つに切り分ける

設定を変更する前に、エンドポイントへ直接1回リクエストを送ってください。この1回で「クライアントの問題／認証の問題／サーバーの問題」を切り分けられます。

# 오류가 클라이언트 문제인지 엔드포인트 문제인지 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ヘッダーで送ります。ゲートウェイは通常前者を想定するため、2つの変数を取り違えると、正常なキーでも401になります。

2つの変数が同時に残っているケースもよくあります。一方を削除し、シェルを新しく開いてから再試行してください。変数ごとの違いはANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEYの違いにまとめています。

429 — 互いに異なる2種類の429

同じ数字でも原因はまったく異なります。サブスクリプションで利用中ならセッションウィンドウの上限に達しており、ウィンドウがリセットされるまで待つ以外に方法はありません。その瞬間には上位プランへの変更も役に立ちません。APIキーで利用中なら、1秒あたりのリクエスト数またはトークン処理量の制限であり、指数バックオフによる再試行でほとんどの場合解決します。

どちらかはANTHROPIC_BASE_URLが設定されているかですぐに判別できます。設定されていれば、サブスクリプションではなくキーを使用中です。サブスクリプション上限の仕組みと、超過時の選択肢についてはClaude Codeの料金で説明しています。

529 overloaded_error — 自分の問題ではないエラー

529は、アップストリームのモデルサーバーが一時的に過負荷であることを意味します。リクエスト内容もキーも残高も原因ではないため、設定を修正して解消できるエラーではありません。対処は再試行だけで、即時再試行より指数バックオフのほうが成功率ははるかに高くなります。

自動フォールバックのあるゲートウェイを経由すると、1つのアップストリームが529を返した際にリクエストが別の経路へ切り替わるため、体感する発生頻度が下がります。英語圏の読者向けの詳細な整理は529 overloaded_errorへの対応をご覧ください。

サブスクリプション上限に達したときに作業を続ける

429がサブスクリプション側のものであれば、待つ代わりにそのセッションだけをキーへ切り替えられます。サブスクリプションを解約する必要はありません。以下の2つの変数が設定されている間だけキーに課金され、削除すれば元に戻ります。

# 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は100万トークンあたり$1.40 / $7.00、Claude Haiku 4.5は$0.70 / $3.50です。前払い残高から差し引かれるため、利用しない月には費用が発生しません。決済手段と国内カードの登録方法はClaude APIの料金・支払いにまとめています。

インストール段階のエラーは別問題です

インストールできない問題は、ほとんどの場合Node.jsのバージョンまたはグローバルインストール権限が原因で、上記3つのエラーとは系統が異なります。まずclaude --versionが正常に出力されるか確認してください。出力されればインストールは完了しており、その後の問題は認証またはネットワーク側です。2つの系統を混同すると、最も時間がかかります。

よくある質問