「Unable to connect to API」の原因と対処 — Claude Code
Claude Codeで「Unable to connect to API」が出たときの原因の見分け方。ConnectionRefusedやENOTFOUNDなどコード別の意味と、curlでの切り分け手順をまとめます。
Unable to connect to API — Claude CodeからAPIへのTCP接続そのものが失敗した、または完了しなかったときに出るエラーです。すでに始まっていたやり取りが途中で切れたのではなく、接続を開く段階でつまずいています。カッコ内に付くコードが原因の見分け方の入り口です。
似た文言の「Waiting for API response」は接続後にデータが届かない保留中の表示で、これとは別物です。原因の場所も違います。このエラーはClaude Codeより手前、ローカルなネットワーク・プロキシ・ファイアウォールに原因があることがほとんどです。
コードが原因の種類を教えてくれる
代表的なコードと意味は次の通りです。Claude Codeが認識しないコードは、そのままカッコ内に表示されます。
| メッセージ | 意味 |
|---|---|
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused) | 意味接続を明示的に拒否された。ファイアウォールかプロキシが遮断している |
Can't reach the API server — check your internet or DNS (ENOTFOUND) | 意味ホスト名が名前解決できない |
No internet route — check your connection or VPN (EHOSTUNREACH) | 意味そのホストへの経路がない |
Couldn't connect through your proxy (ERR_PROXY_TUNNEL) | 意味プロキシ経由のトンネル確立に失敗した |
Connection dropped (ECONNRESET) | 意味接続確立の途中でリセットされた |
Request timed out. Check your internet connection and proxy settings | 意味接続がタイムアウトした |
Connection refusedはConnectionRefusedとECONNREFUSEDの両方の形で出ることがあり、Can't reach the API serverもENOTFOUNDとFailedToOpenSocketのどちらの形もありえます。表記が違っても意味は同じです。
よくある原因は、インターネット接続自体がない、VPNがapi.anthropic.comをブロックしている、必須の社内プロキシが未設定、のいずれかです。
curlで切り分ける
まず、Claude Codeを起動したのと同じ環境でAPIホストに到達できるかを確認します。
curl -I https://api.anthropic.comWindows PowerShellでは、組み込みのInvoke-WebRequestエイリアスに引っかからないようcurl.exe -I https://api.anthropic.comと明示します。単にcurlと打つと別のコマンドが実行され、誤診断につながります。
企業のLLMゲートウェイやリレーを経由している場合、疎通確認の相手先も変わります。ANTHROPIC_BASE_URLを設定して自前のゲートウェイ経由でAnthropicへつないでいる構成では、通信は直接api.anthropic.comへは向かいません。curlで叩く先も、設定したANTHROPIC_BASE_URLのホストに変えて確認します。
このcurlが失敗するなら、原因はClaude Codeより手前にあります。社内プロキシ経由であればHTTPS_PROXYを設定しているか、ファイアウォールが必要なホストを許可しているかを確認します。企業ネットワークでのプロキシ・CA証明書・許可ドメインの設定手順はClaude Codeプロキシ設定にまとめています。
curlは通るのにClaude Codeだけ失敗する場合
これはClaude Codeの手前ではなく、ランタイムとネットワークの間に原因があることが多いパターンです。
- Linux / WSL:
/etc/resolv.confに到達できないネームサーバーが残っていないか確認します。WSLはホストから壊れたリゾルバーをそのまま引き継ぐことがあります - macOS: 切断・アンインストール済みのVPNクライアントが、古いトンネルインターフェースやルーティングルールを残していないか確認します。
ifconfigで古いutunインターフェースが残っていないかを見ます - Docker Desktop: コンテナランタイムが外向き通信を横取りしていることがあります。一度終了して切り分けます
「SSL certificate verification failed」は別系統のエラー
同じUnable to connect to APIで始まっていても、続きが証明書に関するものなら原因も対処もまったく別です。
Unable to connect to API: SSL certificate verification failed. Check your proxy or corporate SSL certificates
Unable to connect to API: Self-signed certificate detectedこれは、ネットワーク上のプロキシやセキュリティ製品がTLS通信を自前の証明書で中継しており、Claude Codeがその証明書を信頼していない状態を指します。コード付きの接続エラーとは原因の場所が違い、対処はNODE_EXTRA_CA_CERTSに組織のCA証明書バンドルを指定することです。NODE_TLS_REJECT_UNAUTHORIZED=0で検証自体を無効化する対処は避けます。証明書の検証をまるごと止めてしまうため、意図しない通信先にも接続してしまいます。
v2.1.199からは、証明書の検証失敗はリトライされず、最初の試行でこのエラーが表示されるようになりました。それより前のバージョンでは、数分かけてリトライしたあとにようやくこのエラーが出ていました。ハンドシェイクのタイムアウトのような一時的なTLS状態は、引き続きリトライの対象です。
クラウドセッションでは原因が別になる
Claude Code on the webやroutine経由のクラウドセッションで似た症状に当たった場合、原因はローカルのネットワーク設定ではありません。クラウドセッションはサンドボックス化されたVM内で動き、送信先はそのクラウド環境の許可リストで絞られています。許可されていない宛先への通信はHTTP 403とx-deny-reason: host_not_allowedで拒否され、証明書が実際の宛先と一致しないTLS証明書として見えることもあります。この場合はローカル側のcurlやプロキシ設定を疑うのではなく、クラウド環境の設定でネットワークアクセスをTrustedからCustomに変え、必要なドメインを許可リストに追加します。
一時的な失敗と恒常的な失敗を分ける
断続的な失敗は自動でリトライされます。何度か試して直るなら、それで終わりです。問題は、リトライしても直らず毎回同じコードで失敗するケースで、これは局所的なネットワークの問題を指しています。
似た症状に見えて原因が別なのが「Socket is closed」です。こちらはストリーミング応答の途中で接続が切れる症状で、v2.1.214以降は企業プロキシ配下でも自動でリトライされるようになりました。Unable to connect to APIは接続を開く段階、「Socket is closed」は開いたあとの切断という違いがあります。
CIや無人セッションではリトライの粘りも見直す
手元の対話セッションなら、リトライが尽きた時点で気づいて対処できます。CIジョブやeval harnessのような無人セッションでは、ネットワークが一時的に不安定なだけで大量のジョブが失敗として終わることがあります。既定のリトライ回数は10回で、CLAUDE_CODE_MAX_RETRIESで上限を変えられますが、v2.1.186以降は15回が上限です。
長めの障害を待ち越したい無人セッションでは、上限を数値で伸ばすよりCLAUDE_CODE_RETRY_WATCHDOG=1を使うほうが向いています。v2.1.199以降、これを設定するとサーバーエラーやタイムアウト、接続断のようなその他の一時的なエラーに対しても既定のリトライ回数が300回、バックオフ込みでおよそ3時間まで増え、CLAUDE_CODE_MAX_RETRIESを明示している場合はその15回の上限も外れます。ただし、これは断続的な失敗を粘り強く待つための設定であり、ここまで説明してきたような恒常的な接続エラーそのものを解消するものではありません。原因を直さないままリトライだけ増やしても、失敗が3時間続くだけです。
必要なホストをファイアウォールで許可する
コンテナ環境や制限されたネットワークでは、通信先を明示的に許可しておく必要があります。中心になるのはapi.anthropic.com(API本体)とclaude.ai・platform.claude.com(認証)です。ほかにも、プラグインのダウンロード先であるdownloads.claude.ai、npm経由のインストールやMCPサーバー取得で使うregistry.npmjs.orgなど、用途ごとに許可すべきホストが分かれます。すべて許可しているつもりでも、片方だけ抜けているとこのエラーだけが再現することがあります。
よくある質問
AWSのdefault-chain credential resolve timed outと同じエラーですか
いいえ、別のエラーです。「Unable to connect to API」はAPIへのTCP接続自体の失敗で、Amazon Bedrock等のAWS経由でもAnthropic API直結でも起こります。AWS固有の「AWS default-chain credential resolve timed out」は、AWSの認証情報解決がローカルで終わらないという別の段階の失敗です。
社内プロキシ経由だとcurlの確認先も変わりますか
ANTHROPIC_BASE_URLで自前のゲートウェイを経由する構成にしている場合は変わります。通信は直接api.anthropic.comへは向かわないため、curlで叩く先もそのゲートウェイのホストに変えて確認します。ゲートウェイの応答が遅い、または詰まっているだけのこともあり、その場合はゲートウェイの運用担当に確認するのが近道です。
Claude Code起動時に出る接続エラーとは違いますか
起動直後、サインイン画面が出る前に出る接続エラーは「Unable to connect to Anthropic services」という別メッセージです。「Unable to connect to Anthropic services」の対処で扱っています。今回のエラーは、サインインを終えたあとの通常利用中に出るものです。
一部だけ許可したファイアウォールでも起きますか
起きます。api.anthropic.comは許可していても、platform.claude.comやdownloads.claude.aiなど用途別の別ホストが漏れていると、その用途のときだけこのエラーが出ます。まとめて許可したつもりでも、機能ごとに宛先が分かれている点を見落としがちです。
まとめ
「Unable to connect to API」はTCP接続そのものの失敗で、原因の多くはClaude Codeより手前のネットワーク・プロキシ・ファイアウォールにあります。まずカッコ内のコードで種類を絞り、curl -I https://api.anthropic.comで同じ環境からの疎通を確認します。curlも失敗するなら社内プロキシやVPNの設定を、curlは通るのにClaude Codeだけ失敗するならDNS設定やVPNの残骸、Docker Desktopの通信横取りを疑います。