この記事の目次
Claude Codeのエラーは、表示された文言を公式のエラー一覧の分類（サーバー・利用上限・認証・ネットワーク・リクエスト）に当てはめると、自分側の問題か提供側の問題かを切り分ける手掛かりになります。症状に応じて、まず次の4つを使い分けます。認証情報は /status、利用上限は /usage、通信は curl -I https://api.anthropic.com、全体の点検は /doctor です。また、画面にエラーが出た時点で、Claude Codeは一時的な失敗をすでに自動で再試行しています。同じ指示を送り直す前に、文言から分類を決めてください。
公式のエラー一覧（Error reference）によると、ここで扱うエラーと復旧コマンドはCLI・デスクトップアプリ・クラウドセッションで共通です。例外はVS Code拡張などの起動元プログラムが出すエラーだけです。エラーではなく操作に迷っている場合は、非エンジニアがつまずきやすいポイントが近い内容です。
Claude Codeのエラーは表示文言からどう分類すればよいか
公式のエラー一覧は、実行時のエラーを「Server errors」「Usage limits」「Authentication errors」「Network and connection errors」「Request errors」などに分けています。インストール時の command not found やセットアップ中のTLS失敗は、別ページ（Troubleshoot installation and login）の担当です。代表的な文言と最初の一手は次のとおりです。
| 表示される文言の例 | 公式の分類 | 原因のありか | 最初の一手 |
|---|---|---|---|
API Error: 500 Internal server error |
Server errors | 提供側 | status.claude.com を見て、1分待って再送 |
API Error: Repeated 529 Overloaded errors |
Server errors | 提供側（全利用者の容量） | 時間を置く、/model で別モデル |
Request timed out |
Server errors（インターネット接続に触れる文言ならネットワーク） | 期限内にAPIが応答しなかった | 再送、ネットワークが正常でも頻発するならネットワークの節へ |
You've hit your session limit · resets ... |
Usage limits | 自分のプランの上限 | /usage でリセット時刻を確認 |
API Error: Request rejected (429) |
Usage limits | APIキーやクラウドのレート制限 | /status で使っている認証情報を確認 |
Not logged in · Please run /login |
Authentication errors | 自分の認証情報 | /login |
Invalid API key · Fix external API key |
Authentication errors | 環境変数などのキー | env | grep ANTHROPIC |
Unable to connect to API |
Network and connection errors | ネットワーク・プロキシ・VPN | curl -I https://api.anthropic.com |
SSL certificate verification failed |
Network and connection errors | 信頼されていない証明書（TLSを傍受する社内プロキシなど） | NODE_EXTRA_CA_CERTS を設定 |
Prompt is too long / Context limit reached · /compact or /clear to continue |
Request errors | 会話と添付の量 | /compact か /clear |
エラーの分類が決まったら、該当する見出しだけ読めば足ります。どれにも当てはまらなければ、最後の見出しに進んでください。
エラーが表示されるまでに何が起きているのか
Claude Codeは、一時的な失敗を指数バックオフで最大10回再試行してからエラーを表示します。公式は、エラーが見えた時点で適用される再試行はすでに済んでいると明記しています。表示直後に指示の再送を繰り返しても、状況が変わっていなければ結果は変わりにくいということです。
再試行中はスピナーに Retrying in Ns · attempt x/y が出ます。応答が20秒届かないと Waiting for API response の表示が出ますが、この段階ではまだ失敗ではありません。ただ、毎回の試行で出るならネットワークの問題として扱うよう公式は案内しています。例外として、TLS証明書の検証失敗は再試行されず初回で表示されます。
回数は CLAUDE_CODE_MAX_RETRIES（既定10）、1リクエストのタイムアウトは API_TIMEOUT_MS（既定600000ミリ秒）で調整できます。
500や529が出たのは自分の設定のせいなのか
基本的に違います。公式は、API自体から返る5xxを「API内部の想定外の失敗」とし、プロンプト・設定・アカウントが原因ではないと書いています。529は全利用者で一時的に容量に達している状態で、利用上限ではなく、消費量にも数えられません。
- 500のとき: status.claude.com で障害を確認し、1分ほど待って再送します。元のメッセージは会話に残っているので、貼り直さず
try againと打てば足ります。障害情報がないのに続くなら/feedbackで報告します。公式によると、500のメッセージ末尾の確認先はプロバイダーで変わり、Amazon Bedrockなどではそのプロバイダーのサービス状態、ANTHROPIC_BASE_URLのゲートウェイではそのホストが示されます。 - 529のとき: 数分おいて再試行します。急ぐなら
/modelで別モデルに切り替えます。公式によると容量はモデルごとに管理されています。 - Request timed out のとき: 接続の期限内にAPIが応答しなかった状態で、既定のタイムアウトは10分です。高負荷時や長い応答の生成中に起こります。再送し、遅いネットワークやプロキシが原因なら
API_TIMEOUT_MSを引き上げます。ネットワークが正常なのに頻発する場合は、後述のネットワークの節を確認します。
「You’ve hit your session limit」と429は何が違うのか
前者のエラーはサブスクリプションの利用枠、後者はAPIキーやクラウドのプロジェクトに設定されたレート制限です。
利用枠を使い切ると You've hit your session limit、You've hit your weekly limit、You've hit your Opus limit、You've hit your Sonnet limit のいずれかが表示されます。公式によると、Claude Codeは表示されたリセット時刻まで以降のリクエストを止めます。セッションと週の上限は全モデル共通なので、モデルを替えても戻りません。一方、OpusとSonnetの上限はそのファミリーへのリクエストだけにかかるため、/model でファミリー外のモデルに切り替えれば続けられます。上限とリセット時刻は /usage で確認します。上限の仕組みは使用制限の解説で扱っています。
Request rejected (429) は、APIキー、Amazon Bedrock、Google Cloudのプロジェクトのレート制限に達した状態です。確認の順としては、まず /status を実行するのがおすすめです。環境に残った ANTHROPIC_API_KEY があると、サブスクリプションではなく低いティアのキーにリクエストが流れることがあるためです。次にプロバイダーのコンソールで制限値を確認し、並列で動かすサブエージェントを減らすなどして並列度を下げます。なお Server is temporarily limiting requests (not your usage limit) はプランと無関係な短時間のスロットルです。公式の対処は、少し待って再試行することです。詳しくはレート制限の解説を参照してください。
「Not logged in」「Invalid API key」「401」はどこから確認するのか
どのエラー文言でも、まず /status で、いま有効な認証情報がどれかを見ます。ログインしたつもりでも、環境変数のAPIキーが優先されていることがあるためです。
- Not logged in: 公式の説明では、このセッションで使える有効な認証情報がない状態です。
/loginを実行します。環境変数で認証するつもりなら、claudeを起動したシェルでANTHROPIC_API_KEYがexportされているかを確認します。 - Invalid API key: 公式の説明では、
ANTHROPIC_API_KEYまたはapiKeyHelperスクリプトが返したキーをAPIが拒否したか、送信前にClaude Codeが止めた状態です。公式によると、direnvやIDEのターミナルがプロジェクトの.envから古いキーを読み込むことがあります。下のコマンドで中身を確認し（キーの値が表示されるので、出力を人に共有しないでください）、サブスクリプションで使うならキーを外して/loginします。 - API Error: 401 Invalid authentication credentials: 公式は期限切れが原因ではないと明言しています。認証情報の取り消し、組織の無効化やアクセス削除、アカウント停止のいずれかです。
/statusに使用中のAPI key行があれば、そのキーがログインより優先されるため/loginでは置き換わりません。
env | grep ANTHROPIC
unset ANTHROPIC_API_KEY原因が分からないままログインに失敗するなら、/logout、Claude Codeを閉じる、claude で起動して認証し直す、の順でやり直します。何度もログインを求められる場合は、トークンの検証が時刻に依存するためシステムの時計を確認します。症状別の対処はログインできないときの対処にまとめています。
「Unable to connect to API」やSSL証明書エラーはどう切り分けるのか
公式によると、ネットワーク系のエラーの多くはローカルのネットワーク、プロキシ、ファイアウォールに由来します。まず同じシェルからAPIに届くかを確かめます。
curl -I https://api.anthropic.com届かなければ、インターネット接続、VPN、社内プロキシを疑います。社内プロキシの内側なら、起動前に HTTPS_PROXY を設定します。curlは通るのにClaude Codeだけ失敗する場合は、ANTHROPIC_BASE_URL が残っていないかを確認します。設定されているとClaude Codeはその宛先に送るため、もう動いていないプロキシを指していると Connection refused になります。
SSL certificate verification failed や Self-signed certificate detected は、Claude Codeが信頼していない認証局の証明書に当たった状態です。公式は、典型的な原因としてネットワーク経路上のTLSを傍受する社内プロキシや、プライベートCAで署名されたゲートウェイを挙げています。組織のCAバンドルを NODE_EXTRA_CA_CERTS で指定します。公式は、検証を丸ごと無効にする NODE_TLS_REJECT_UNAUTHORIZED=0 は設定しないよう明記しています。設定の詳細はネットワークエラーの対処で扱っています。
「Prompt is too long」はどう解消するのか
リクエスト容量（会話と添付ファイルの合計）がコンテキストウィンドウを超えた状態で、対話中は Context limit reached · /compact or /clear to continue と表示されます。/compact で以前のやり取りを要約するか、/clear で新しく始めます。繰り返すなら /context で何が容量を使っているかを確認し、使っていないMCPサーバーを /mcp disable <name> で外します。自動コンパクトは既定でオンなので、切っていれば戻します。仕組みはコンテキストウィンドウの解説で説明しています。
インストール直後の「command not found」や権限エラーはどこを見るのか
公式のエラーの振り分けでは、command not found、PATHの問題、EACCES、セットアップ中のTLSエラーはインストールとログインのトラブルシューティングページの担当です。まず次のコマンドでバージョンが出るかを確かめ、command not found なら、まずPATHを確認します。npmで入れていてnpm特有の権限エラーが出る場合、公式はネイティブインストーラーへの切り替えを案内しています。
claude --versionOS別の手順はインストールガイドとWindowsでの導入ガイドにまとめています。
-p実行やCI、VS Codeでだけ失敗するのはなぜか
-p やCIで認証エラーが出る場合は、認証情報の渡し方を確認します。公式によると、ログインの取り消しや期限切れのとき、-p とAgent SDKでは Failed to authenticate: OAuth token revoked. や Failed to authenticate. API Error: 401 OAuth token has expired のような表示になり、構造化エラーコードは authentication_failed です。保存済みのログインを使うなら、同じ環境で claude を起動して /login してから再実行します。対話でログインできない自動化では、ANTHROPIC_API_KEY を使うか、claude setup-token で長期トークンを作ります。無人のCIで429や529の容量エラーに当たる場合は、CLAUDE_CODE_RETRY_WATCHDOG を 1 にすると、その容量エラーを回数で打ち切らずに再試行し続けます。GitHub Actionsでの組み立てはGitHub Actionsの活用ガイドで扱っています。
VS Codeなどで Error: Claude Code process exited with code 1 のように終了コード付きで出るのは、起動元プログラムが出すエラーです。公式は、終了コードだけでは原因が分からず、本当のエラーはプロセスの出力にあると説明しています。VS Codeでは、表示される View output logs から中身を確認します。
どの分類にも当てはまらないときは何をすればよいか
エラー一覧にない、または対処で直らない場合に公式が挙げている手段を、本記事で勧める確認順に並べます。
- Claude Codeの中で
/doctorを実行します。インストール、設定、拡張、コンテキスト使用量を点検し、確認のうえ適用できる修正を提案します。claudeが起動しないなら、シェルからclaude doctorを実行します。 - status.claude.com で進行中のサーバー障害を確認します。
/feedbackで会話の記録と説明をAnthropicへ送ります。Amazon Bedrockなど他社プロバイダー経由の場合は、送信ではなくローカルにアーカイブが保存されます。- GitHubのanthropics/claude-codeで既存のissueを検索します。
設定が反映されない、フックが動かないといった文言のない不具合は、公式では別ページ（Debug your configuration）の担当です。記録を残して追いたい場合はエラーログの確認方法を参照してください。アカウント、請求、サブスクリプションの問題は、claude.aiの左下の頭文字から Get help を選び、Anthropicのサポートに連絡します。
エラーの文言はバージョンアップで書き換わることがあり、公式の一覧にも以前の表記についての注記があります。この記事の文言と完全に一致しない場合は、表の「原因のありか」で当たりをつけ、公式のError referenceで最新の表記を照合してください。
Claude Codeの使い方を体系立てて学び直したい場合は、月額1,980円から参加できる学習コミュニティAI駆動ラボで追えます。