Unable to connect to API は、Claude Code が現在の API route との TCP 接続を完了できなかったことを示します。API が 401、429、500、529 を返した状態とは別です。まず現在の Claude Status を確認し、Claude Code を起動したのと同じ shell で次を実行してください。
bashcurl -I https://api.anthropic.com
curl も接続できなければ、その環境の DNS、firewall、VPN、proxy、TLS を調べます。curl は HTTP response を受け取れるのに Claude Code だけ失敗する場合は、/status、proxy/CA 変数、WSL や macOS、Docker、ANTHROPIC_BASE_URL が選ぶ実際の host を確認します。
| 表示される suffix | 絞り込める範囲 | 最初の確認 |
|---|---|---|
ECONNREFUSED | 接続先または local proxy が接続を拒否 | 実際の endpoint と proxy address |
ECONNRESET | 確立済みの接続が VPN、proxy、network device、remote side により切断 | 別の信頼できる network で 1 回比較 |
ETIMEDOUT | 制限時間内に接続経路が完成しなかった | DNS、firewall、proxy、route latency |
fetch failed | API response を得る前の network layer failure | 次の error line と同一 shell test |
| certificate / self-signed certificate | TLS inspection または corporate CA の不足 | 承認済み CA bundle の設定 |
| HTTP status と JSON body | API または provider まで到達済み | 接続分岐を離れ、status ごとに処理 |
再インストール、Key の変更、VPN の切り替え、DNS の変更、model の変更を同時に行わないでください。偶然直っても、再発時に原因を説明できません。
本当に接続エラーかを確定する
Anthropic の Claude Code error reference では、Unable to connect to API、ECONNREFUSED、ECONNRESET、ETIMEDOUT、fetch failed、network/proxy を含む timeout が network error に分類されています。重要なのは HTTP response の有無です。
- status code、response body、request ID がない：接続経路を調べる。
401または invalid key が返る：network は API layer に到達しているため、authentication を調べる。429、500、529が返る：API または設定中の provider が応答しているため、個別の status を処理する。Connection closed mid-responseが出る：streaming は開始済みです。完了した block を残し、最後の完全な位置から続けます。
Claude Code は一時的な connection failure や server error を自動で再試行します。最終的なエラーが terminal に出た時点で、短時間の自動回復では解消しなかった可能性が高い状態です。同じ条件で Enter を繰り返しても、診断情報は増えません。
Claude Code を起動した shell で baseline を取る
browser、WSL、SSH、VS Code Remote、container は、それぞれ異なる DNS、proxy、certificate store を使う場合があります。browser で claude.ai が開くことは、claude process が api.anthropic.com に到達できる証明ではありません。
host への接続と route 関連の変数だけを確認します。
bashcurl -I https://api.anthropic.com env | grep -Ei '^(ANTHROPIC_BASE_URL|ANTHROPIC_API_KEY|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|NODE_EXTRA_CA_CERTS)='
API key や proxy password が出る場合は、結果を issue やチャットへ貼らないでください。必要なのは、変数が存在するか、どの host、proxy、certificate file を選んでいるかだけです。
| curl | Claude Code | 次に見る場所 |
|---|---|---|
| host を resolve できない | 失敗 | DNS または WSL resolver |
| port 443 が timeout | 失敗 | Firewall、VPN、proxy、outbound route |
| certificate validation error | 失敗 | TLS inspection と CA trust |
| 任意の HTTP response を受け取る | 接続エラー | Claude Code の process environment、scope、gateway |
| response を受け取る | 401/429/500/529 | 純粋な connection error ではない |
curl -I の成功は basic reachability を確認するだけです。account、full request、model、gateway compatibility まで確認したことにはなりません。
curl も失敗する場合は network path を直す
status page が green でも、すべての地域、ISP、企業 network が正常とは限りません。そのうえで、1 つの条件だけを変えます。
- mobile hotspot や家庭 network など、別の信頼できる回線で同じ curl を 1 回実行する。
- VPN が active なら、切断後に 1 回だけ比較する。組織で VPN が必須なら、policy を迂回せず network team に allowlist を確認してもらう。
- 実際に使用する API host と公式の network access requirements が firewall で許可されているか確認する。
- Linux/WSL では
/etc/resolv.confの nameserver が到達可能か確認する。Windows 側の browser が正常でも WSL resolver は壊れます。 - DNS は成功するのに 443 が timeout するなら、credential ではなく firewall、router、proxy、outbound route を調べる。
ECONNREFUSED は、実際の host または local proxy port が接続を拒否したときに起きやすい症状です。ANTHROPIC_BASE_URL が別の host を選んでいないか確認します。ECONNRESET は一度つながった connection が切られた状態なので、VPN、TLS inspection、network quality、long-lived connection policy が有力です。
Corporate proxy と custom CA を正しく設定する
Claude Code は起動時に標準の proxy 変数を読み取ります。
bashexport HTTPS_PROXY=https://proxy.example.com:8080 export NO_PROXY=".example.internal" claude
scheme、host、port は組織から指定された値を使います。Claude Code は SOCKS proxy をサポートしていません。proxy が TLS inspection を行う場合は、承認された CA bundle を設定します。
bashexport NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem claude
NODE_TLS_REJECT_UNAUTHORIZED=0 は certificate verification を無効にするため使わないでください。proxy credential を repository の script に保存するのも避けます。settings scope と CA store の違いは公式の enterprise network configuration で確認できます。
Claude Code 起動後に export した変数は、実行中の process には反映されません。変更後は再起動します。Desktop-managed session、cloud session、background supervisor では shell variable が有効 scope でない場合があるため、/status と debug log で確認します。
curl は成功し Claude Code だけ失敗する場合
Claude Code 内で /status を実行し、active credential、provider、proxy、endpoint が意図どおりか確認します。
- Unexpected API key：
ANTHROPIC_API_KEYがあると、subscription login ではなく API-key route を選ぶ場合があります。secret の値は表示しないでください。 - Unexpected gateway：
ANTHROPIC_BASE_URLは destination を変更します。official API と third-party relay を同じ障害として扱わないでください。 - WSL / remote IDE：host terminal、WSL、実際の VS Code Remote shell で同じ curl を実行し、DNS、proxy、CA の差を確認します。
- macOS の古い VPN route：切断・削除済みの VPN が
utuninterface や network extension を残すことがあります。System Settings で確認し、不明な route を無作為に削除しないでください。 - Docker Desktop：container runtime が outbound traffic に影響する場合があります。作業に安全なら、停止した状態で 1 回だけ比較します。
- Background process：supervisor が別 shell の古い環境を引き継いでいる場合は、supported user settings または managed settings に network variable を置きます。
route の優先順位が不明なら、先に Claude Code API configuration で authentication と provider を整理します。
小さな request で復旧を確認する
1 つ変更したら Claude Code を再起動し、機密情報を含まない短い request を送ります。次の 3 点がそろえば復旧です。
- 同じ shell が official host または承認済み gateway から HTTP response を受け取る。
/statusが期待した authentication と route を示す。- 新しい request が同じ connection error なしで完了する。
HTTP status に変わった場合、transport route は前進しています。Claude Code API Error 500、Claude API 529 overloaded、Claude API rate limit の該当ページへ移動してください。server response があるのに network 設定を切り替え続ける必要はありません。
Support に渡す情報を最小化する
日時と timezone、OS、Claude Code version、正確な error suffix、route type、curl -I の結果、status page の観察、network または proxy を 1 つ変えた結果を記録します。ANTHROPIC_BASE_URL の host は、private address でない場合だけ共有します。
API key、OAuth token、proxy password、private prompt、customer data、完全な environment dump は送らないでください。official route は Help Center または利用可能な /feedback、corporate network や gateway はその owner へ、同じ redacted packet を送ります。
判断は 3 つです。同じ shell の curl も失敗するなら host までの経路、curl は成功して Claude Code だけ失敗するなら process environment、HTTP error が返るなら connection ではなく response を直します。
