Claude Codeがエラーで動かない時の切り分け手順──400・401・403は「認証の優先順位」を疑う

Claude Codeが動かない時にやるべきなのは、エラー文をそのまま検索することではなく「どの層で止まっているか」の切り分けだ。層は認証・API・ネットワーク・設定の4つに分かれる。このうち日本語で情報が薄いのが認証層で、Anthropic公式ドキュメントによるとClaude Codeの認証には7段階の優先順位があり、Claudeサブスクリプションを契約していても環境変数にANTHROPIC_API_KEYが残っていればそちらが勝つ。400も401も403も、実体はここで起きていることがある。

3行まとめ

1. Anthropic公式のClaude API errorsによると、400はinvalid_request_error、401はauthentication_error、403はpermission_errorで別レイヤーの問題。401は資格情報そのもの、403は権限、400はリクエスト内容または「組織が無効化されている」ケース（2026年8月14日に公式ドキュメントを確認）
2. Claude Codeの認証優先順位は7段階。1位がクラウドプロバイダ、2位がANTHROPIC_AUTH_TOKEN、3位がANTHROPIC_API_KEY、7位（最下位）が/loginで入れたサブスクのOAuth資格情報。公式は非対話モード（-p）ではAPIキーが存在すれば常に使われると明記している
3. 当サイトは2026年7月6日、~/.claude/settings.jsonのenvブロックにエンドポイントURLとモデルIDを書き込み、実行中だった複数セッションが一斉に401ループに陥る事故を起こした。公式はenvを「すべてのセッションと、Claude Codeが起動するサブプロセスに適用される環境変数」と定義している

最初に打つのは検索ではなく2つのコマンド

Anthropic公式のTroubleshootingページは、どこで詰まっているか分からない場合はまず/doctorを実行するよう案内している。インストール・設定・拡張・コンテキスト使用量を自動チェックし、修正案を提示して確認後に適用する。claude自体が起動しない場合は、シェルからclaude doctorを実行するとセッションを起こさずに診断だけ出る。

もう1つが/statusだ。公式Error referenceの認証エラー項目には、対処法としてほぼ全てに「Run /status to confirm active credential」が並んでいる。Login methodの行にサブスクのアカウントが出て、APIキーが使われている時はAPI keyの行が追加される。ここが想定と違えば、原因は認証層にある。

エラーコードが指している層

Anthropic公式のClaude API errorsページ（2026年8月14日確認）は、HTTPステータスとエラータイプの対応を次のように定義している。

401と403は別物だ。401は「その資格情報が通らない」、403は「通ったが権限がない」。混同すると、キーを作り直しても直らない、ロールを変えても直らないという堂々巡りになる。なお公式SDKは接続エラー・レート制限・5xxを指数バックオフで既定2回まで自動リトライし、retry-afterヘッダがあれば尊重すると明記されている。

401の本体は「どの資格情報が選ばれたか」

Claude Code公式のAuthenticationページは、複数の資格情報が存在する場合の選択順を7段階と定めている（2026年8月14日確認）。上にあるものが勝つ。

公式は、対話モードではAPIキーを使うか一度だけ確認プロンプトが出て選択が記憶されること、非対話モード（-p）ではAPIキーが存在すれば常に使われることを明記している。CIやスクリプトで動かした時だけ挙動が変わるのはこれが理由だ。

公式が挙げている診断コマンドはenv | grep ANTHROPIC。環境に紛れ込んだ変数を洗い出すためのものだ。ただし出力にAPIキー本体が含まれるので、画面共有中やGitHub Issueに貼るログには含めないほうがいい（この注意は公式の記載ではなく当サイトの運用上の補足）。キーが正しく見えるのに通らない場合、公式はInvalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41という実例を挙げ、「貼り付けではなく打ち直す」「バイトオーダーマークやゼロ幅スペースなどの不可視文字を確認する」を対処として示している。

原因が絞れない場合の再認証手順は、/logoutでサインアウトし、Claude Codeを閉じ、claudeで再起動する3手順。WSL2・SSH・コンテナではブラウザが別ホストで開きローカルのコールバックサーバに戻れないため、表示されるコードをPaste code here if promptedに貼り付ける形になる。macOSではKeychainがロックされていると資格情報を保存できずログインに失敗するので、claude doctorでKeychainアクセスを確認する。

サブスク契約中なのに400が出るケース

Claude Code公式のTroubleshoot installation and loginページには「This organization has been disabled with an active subscription」という節がある。有効なサブスクリプションがあるのにAPI Error: 400 ... "This organization has been disabled"が出る場合、ANTHROPIC_API_KEY環境変数がサブスクリプションを上書きしている、という説明だ。公式は「前職や前のプロジェクトの古いAPIキーがシェルのプロファイルに残っているケースがよくある」と書いている。

エラーコードは400（リクエスト不正）だが、原因は認証設定側にある。コードだけを頼りにリクエストの中身を疑うと直らない。対処は環境変数を消すことだ。macOS/Linuxではunset ANTHROPIC_API_KEYしてからclaude、Windows PowerShellではRemove-Item Env:ANTHROPIC_API_KEY。恒久的に消すには~/.zshrc・~/.bashrc・~/.profileにexport ANTHROPIC_API_KEY=...の行がないか確認し、作業後に/statusで有効な認証方式を確認する、というのが公式の手順だ。

自社の事故ログ：settings.jsonのenvで複数セッションが401ループになった

当サイトは2026年7月6日、これに近い事故を自分で起こしている。別ベンダーが提供するAnthropic API互換エンドポイントでClaude Codeを動かす検証中、~/.claude/settings.jsonのenvブロックにANTHROPIC_BASE_URLと各モデルエイリアスのモデルIDを書き込んだ。作業メモには「settings.jsonは触らない、env VAR=... claudeで使い捨てディレクトリから起動する」と明記していたのに無視した形だ。結果、モデル選択でAnthropicのモデルを選んでもリクエストが互換エンドポイント側へ向き、認証が通らず401が繰り返された。影響は検証セッションに留まらず、同時に動いていた無関係な複数セッションが一斉に使えなくなった。

理由は公式ドキュメントで説明がつく。Claude Code公式のSettingsページはenvブロックを「すべてのセッションと、Claude Codeが起動するサブプロセスに適用される環境変数」と定義し、シェルのexportを打ち消すには変数に""を設定すると書いている。つまりenvの値はシェルの環境変数より後に効く。ユーザーレベルの~/.claude/settings.jsonに書けば、以後起動するすべてのセッションが同じ向き先を引き継ぐ。

この事故から得た運用上の結論は2つだ。別エンドポイントを試す時はグローバルな設定ファイルに書かず、env VAR=... claudeの形で使い捨てディレクトリから起動すること。そして障害が「複数セッションで同時に」起き始めたら、コードやネットワークではなくグローバル設定を最初に疑うこと。1セッションだけの障害と全セッションの障害は、原因の在りかが違う。

403・429・5xxとネットワーク層

403の確認先として公式が挙げているのは、Pro/Maxならclaude.ai/settingsでサブスクリプションが有効か、Consoleならアカウントに「Claude Code」または「Developer」ロールが付いているか（割り当てはSettings → Membersで管理者が行う）、そして企業プロキシがAPIリクエストに干渉していないかの3点。3番目は見落としやすく、403がAnthropic側の権限ではなく間に挟まったプロキシの応答であるケースがある。

429は2つの別物が混在する。Claude API errorsページは「まれに、組織の使用量が急増した場合、APIの加速度制限によって429が出ることがある」と書き、対策に「トラフィックを段階的に増やす」ことを挙げている。Claude Code側では使用量上限（You've hit your session limitなど）とAPI Error: Request rejected (429)が別項目で、後者にはCLAUDE_CODE_MAX_TOOL_USE_CONCURRENCYを下げる対処が示されている。5xxと529は「サーバ側の問題で通常は一時的」と分類され、status.claude.com の確認が第一の対処だ。この帯で設定を触り始めると、直っていないのに直したと錯覚しやすい。

接続系では、公式はUnable to connect to APIに対してインターネット接続、ファイアウォール／プロキシ設定、ANTHROPIC_BASE_URLが正しいかの3点を確認先に挙げている。3つ目は前述の事故と同じで、接続できない原因が「向き先が変わっている」ことである場合がある。また「エラーは出ないが設定が効かない」時、公式はpermissions・hooks・envが無視される原因として「~/.claude.jsonはアプリの状態とUIトグルを保持するファイル。これらは~/.claude/settings.jsonに属する。2つは別のファイルである」と明記している。ドット1つの違いだ。

Claude Code自体の位置づけから確認したい場合はClaude Codeとは何かを整理した記事を、プラン別の料金と機能の対応はClaude Codeの料金・機能ガイドを参照してほしい。

切り分けの実行順序

正直な但し書き

確認できていないこと・この記事の限界を書いておく。

1. 一次情報はすべて2026年8月14日にAnthropic公式ドキュメントを取得して確認したもので、それ以降の変更は反映していない。Claude Codeはバージョン単位で挙動が変わり、公式ドキュメント自体が「v2.1.208以前は」といった但し書きを多数含む。claude --versionで自分の環境を確認してから読み合わせてほしい。

2. エラー文言は英語版ドキュメントからの引用で、日本語環境での表示は検証していない。検索する際は本記事の英語文言をそのまま使うほうが公式ページに当たりやすい。

3. 自社の事故ログは1件（2026年7月6日）の実例であり、統計ではない。envブロックの上書きが複数セッションに波及した理由は公式の記述と整合するが、当時ログを取って因果を検証したわけではなく、事後に公式ドキュメントを読んで再構成した説明である。同じ症状の全てが同じ原因だとは言えない。

4. Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundry経由の構成は当サイトで運用していない。公式の記載は引用したが実機での再現確認はしていない。

5. 本記事は特定の手順で復旧することを保証しない。アカウント状態、組織のポリシー設定、企業ネットワークの構成に依存する部分が大きい。公式は最終導線として、claude.ai（Consoleユーザーはplatform.claude.com）にサインインし左下のイニシャルから「Get help」を選ぶサポート窓口を案内している。競合記事の調査は行っておらず、「この情報は他にない」という主張はしない。

出典

• Authentication — Claude Code公式ドキュメント（2026年8月14日確認）：https://code.claude.com/docs/en/authentication
• Error reference — Claude Code公式ドキュメント（2026年8月14日確認）：https://code.claude.com/docs/en/errors
• Troubleshoot installation and login — Claude Code公式ドキュメント（2026年8月14日確認）：https://code.claude.com/docs/en/troubleshoot-install
• Troubleshooting — Claude Code公式ドキュメント（2026年8月14日確認）：https://code.claude.com/docs/en/troubleshooting
• Claude API errors — Anthropic公式ドキュメント（2026年8月14日確認）：https://platform.claude.com/docs/en/api/errors
• Environment variables — Claude Code公式ドキュメント（2026年8月14日確認）：https://code.claude.com/docs/en/env-vars
• Settings — Claude Code公式ドキュメント（2026年8月14日確認）：https://code.claude.com/docs/en/settings
• Debug your configuration — Claude Code公式ドキュメント（2026年8月14日確認）：https://code.claude.com/docs/en/debug-your-config
• Anthropic status page：https://status.claude.com