「Unable to connect to API」の原因と対処 — Claude Code

Unable to connect to API — Claude CodeからAPIへのTCP接続そのものが失敗した、または完了しなかったときに出るエラーです。すでに始まっていたやり取りが途中で切れたのではなく、接続を開く段階でつまずいています。カッコ内に付くコードが原因の見分け方の入り口です。

似た文言の「Waiting for API response」は接続後にデータが届かない保留中の表示で、これとは別物です。このエラーの原因はClaude Codeより手前、つまりローカルのネットワーク・プロキシ・ファイアウォール・接続先の設定にあります。

コードが原因の種類を教えてくれる

代表的なコードと意味は次の通りです。Claude Codeが認識しないコードは、そのままカッコ内に表示されます。

Connection refusedはConnectionRefusedとECONNREFUSEDの両方の形で出ることがあり、Can't reach the API serverもENOTFOUNDとFailedToOpenSocketのどちらの形もありえます。表記が違っても意味は同じです。

表示形式はv2.1.227で変わっています。旧形式との違いは、後半の版ごとの変更点の表にまとめました。

切り分けは3手で足りる

原因の候補として公式に挙がっているのは、インターネット接続そのものがない、VPNがapi.anthropic.comをブロックしている、必須の社内プロキシが未設定、の3つです。

手順1: curlで疎通を見る

Claude Codeを起動したのと同じシェルで、次のコマンドを実行します。

curl -I https://api.anthropic.com

Windows PowerShellでは、組み込みのInvoke-WebRequestエイリアスに引っかからないようcurl.exe -I https://api.anthropic.comと明示します。単にcurlと打つと別のコマンドが実行され、誤診断につながります。

失敗時にcurlが何を返すかも知っておくと、Claude Codeのコードと突き合わせやすくなります。待ち受けのないローカルポートに接続して確かめた実際の出力です(macOSのcurl 8.7.1で確認)。after 0 msの部分は環境によって変わります。

curl -sS -I http://127.0.0.1:9
# curl: (7) Failed to connect to 127.0.0.1 port 9 after 0 ms: Couldn't connect to server
# 終了コードは 7

curlの終了コード7は「接続できなかった」で、拒否された場合もここに入ります。Claude Code側のConnection refusedに相当する状況です。

企業のLLMゲートウェイやリレーを経由している場合、疎通確認の相手先も変わります。ANTHROPIC_BASE_URLを設定していると、通信は直接api.anthropic.comへは向かいません。ゲートウェイ自体に届くかを見るために、curlの宛先も設定したホストに替えます。

curlが失敗するなら、HTTPS_PROXYの設定と、ファイアウォールが必要なホストを許可しているかを見ます。企業ネットワークでのプロキシ・CA証明書・許可ドメインの設定手順はClaude Codeプロキシ設定にあります。

curlは通るのにClaude Codeだけ失敗する場合

多くの場合、ランタイムとネットワークの間に原因があります。

手順2: 消えたゲートウェイの設定が残っている

echo $ANTHROPIC_BASE_URL(PowerShellはecho $env:ANTHROPIC_BASE_URL)と、settingsファイルのenvブロックの両方を見ます。ANTHROPIC_BASE_URLが設定されていると、Claude Codeはモデルへのリクエストをapi.anthropic.comではなくそのアドレスへ送ります。すでに停止したローカルのプロキシやゲートウェイを指す値がシェルのプロファイルやsettingsのenvに残っていると、curlはapi.anthropic.comに届くのにConnection refusedが出ます。値を消して、新しいターミナルからClaude Codeを起動し直します。

手順3: OSとコンテナ環境の残骸

• Linux / WSL: /etc/resolv.confに到達できないネームサーバーが残っていないか確認します。WSLはホストから壊れたリゾルバーをそのまま引き継ぐことがあります
• macOS: 切断・アンインストール済みのVPNクライアントが、古いトンネルインターフェースやルーティングルールを残していないか確認します。ifconfigで古いutunインターフェースを探し、見つかればシステム設定でそのVPNのネットワーク拡張を削除します
• Docker Desktop: コンテナランタイムが外向き通信を横取りしていることがあります。一度終了して切り分けます

「SSL certificate verification failed」は別系統のエラー

同じUnable to connect to APIで始まっていても、続きが証明書に関するものなら原因も対処もまったく別です。v2.1.273以降の表示は、OpenSSLのコードと対処のヒントまで含みます。

Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). The certificate comes from an authority Claude Code doesn't trust, ... set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store
Unable to connect to API: Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN). The certificate comes from an authority Claude Code doesn't trust, ...

これは、ネットワーク上のプロキシやセキュリティ製品がTLS通信を自前の証明書で中継しており、Claude Codeがその証明書を信頼していない状態です。対処はNODE_EXTRA_CA_CERTSに組織のCA証明書バンドルを指定するか、CAをシステムの証明書ストアに追加することです。NODE_TLS_REJECT_UNAUTHORIZED=0で検証自体を無効化する対処は避けます。証明書の検証をまるごと止めてしまうため、意図しない通信先にも接続してしまいます。

同じ証明書の失敗でも、/loginと起動時の接続チェックでは別の文言になります。SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). ...で始まり、末尾にclaude doctorの実行を促す一文が付きます。

手元のv2.1.285では、claude doctorがヘルプのサブコマンド一覧に載っています。シェルから打つclaude doctorは読み取り専用の診断です。セッション中の/doctorは、問題の修正まで行える、より広いチェックアップです。

証明書の検証失敗はリトライされず、最初の試行でこのエラーが表示されます。ハンドシェイクのタイムアウトのような一時的なTLS状態は、引き続きリトライの対象です。

クラウドセッションでは原因が別になる

Claude Code on the webやroutine経由のクラウドセッションで似た症状に当たった場合、原因はローカルのネットワーク設定ではありません。クラウドセッションはサンドボックス化されたVM内で動き、送信先はそのクラウド環境の許可リストで絞られています。許可されていない宛先への通信はHTTP 403とx-deny-reason: host_not_allowedで拒否され、証明書が実際の宛先と一致しないTLS証明書として見えることもあります。

この場合はローカル側のcurlやプロキシ設定を疑わず、クラウド環境の設定でネットワークアクセスをTrustedからCustomに変えます。そのうえで必要なドメインを許可リスト(Allowed domains)に追加します。共有された組織環境は読み取り専用で開くため、変更にはオーナーへの依頼が要ります。

断続的な失敗はリトライされる

断続的な失敗は自動でリトライされます。何度か試して直るなら、それで終わりです。問題は、リトライしても直らず毎回同じコードで失敗するケースで、これは局所的なネットワークの問題を指しています。

似た症状に見えて原因が別なのが「Socket is closed」です。こちらはストリーミング応答の途中で接続が切れる症状で、自動リトライの対象です。Unable to connect to APIは接続を開く段階、「Socket is closed」は開いたあとの切断という違いがあります。

CIや無人セッションではリトライの粘りも見直す

手元の対話セッションなら、リトライが尽きた時点で気づいて対処できます。CIジョブやeval harnessのような無人セッションでは、ネットワークが一時的に不安定なだけで大量のジョブが失敗として終わることがあります。リトライ回数は次の3段階で決まります。

CLAUDE_CODE_MAX_RETRIESで上限を変えられますが、数値を上げても15回までです。長めの障害を待ち越したい無人セッションでは、CLAUDE_CODE_RETRY_WATCHDOG=1のほうが向いています。

このwatchdogは、サーバーエラーやタイムアウト、接続断といった一時的なエラーの既定回数を300回に引き上げ、CLAUDE_CODE_MAX_RETRIESを明示している場合は15回の上限も外します。さらに429と529の容量エラーは回数の制限なく再試行します。バックオフの間隔は最大5分で、リセット時刻つきの応答ならその時刻まで待ちます。ただし、支出上限や利用枠の枯渇を伝える標準速度の429は、待たずに即座に失敗します。

これは断続的な失敗を粘り強く待つための設定で、恒常的な接続エラーそのものは解消しません。原因を直さないままリトライだけ増やしても、失敗が3時間続くだけです。

必要なホストをファイアウォールで許可する

コンテナ環境や制限されたネットワークでは、通信先を明示的に許可しておく必要があります。中心になるのはapi.anthropic.com(API本体)と、認証に使うclaude.ai・platform.claude.comです。用途別のホストは次の通りです。

api.anthropic.comだけ許可して他が抜けていると、その用途を使ったときにだけ接続エラーになります。

ゲートウェイ経由でANTHROPIC_BASE_URLを使っていても、fast modeの利用可否チェックはapi.anthropic.comを呼びます。このチェックは設定済みのHTTPプロキシを経由し、プロキシ経由でも届かないときだけ失敗します。ゲートウェイが発行した資格情報をAnthropicが拒否した場合も同じ接続エラーになり、こちらは許可リストを足しても直りません。

同じ型の例がもう1つあります。Bedrock・Agent Platform・Foundry経由で使っていても、WebFetchのドメイン安全チェックはapi.anthropic.comを呼びます。ブロックされた環境ではskipWebFetchPreflight: trueでこのチェックを省けます。

ほかに、storage.googleapis.comはv2.1.116より前のネイティブインストーラーと自動更新でも使われます。古いバージョンを固定運用している環境では、この点も許可リストの確認対象です。ブラウザーでのclaude.aiサインインが開くclaude.comも、許可の確認先に入れておきます。

バージョンごとの変更点

エラー文言やリトライの挙動は、次のバージョンで変わっています。古いバージョンで見たメッセージが今と違うのは、この表のためです。

よくある質問

AWSのdefault-chain credential resolve timed outと同じエラーですか

いいえ、別のエラーです。「Unable to connect to API」はAPIへのTCP接続自体の失敗で、AWS固有の「AWS default-chain credential resolve timed out」は、AWSの認証情報解決がローカルで終わらないという別の段階の失敗です。

Claude Code起動時に出る接続エラーとは違いますか

初回セットアップ時、サインイン画面が出る前に出る接続エラーは「Unable to connect to Anthropic services」という別メッセージです。「Unable to connect to Anthropic services」の対処で扱っています。今回のエラーは、サインインを終えたあとの通常利用中に出るものです。OAuthのログイン画面がtimeout of 15000ms exceededで止まるなら、auth.anthropic.comのDNS解決失敗が該当します。

まとめ

同じシェルのcurlが通るのに毎回同じコードで失敗するなら、疑う先はネットワークではなく、Claude Codeが読んでいる設定です。まずANTHROPIC_BASE_URLを見ます。コードではなく証明書の文言が続いているなら、別系統のエラーとして、CA証明書の設定に話が移ります。