Unable to connect to API
APIサーバーに到達できていない状態。末尾の括弧内のコードで原因が特定できる。
エラー文字列
Unable to connect to API
何が起きているか
API サーバーへの接続そのものが確立できていません。リクエストが送れていないので、認証やプランの問題ではありません。
⭐ メッセージの末尾に括弧付きのエラーコードが出ます。ここで原因がほぼ確定します。 まずそれを読んでください。
| コード | 意味 | 主な原因 |
|---|---|---|
ENOTFOUND |
名前解決に失敗 | DNS の問題。社内DNSが外部を引けていない |
ECONNREFUSED |
接続を拒否された | ポートが閉じている。プロキシの設定先が間違っている |
ETIMEDOUT |
応答が無いまま時間切れ | ファイアウォールが黙って落としている |
EHOSTUNREACH / ENETUNREACH |
経路が無い | VPN の分割トンネル設定、ネットワーク未接続 |
ECONNRESET |
接続を切られた | プロキシや IDS が途中で遮断している |
EPROTO / ERR_TLS_* |
TLS の失敗 | 証明書の問題（SSL certificate verification failed を参照） |
同じ系統のメッセージとして Connection refused — / Can't reach the API server — / No internet route — / Couldn't connect through your proxy / Connection dropped も出ます。対処は同じです。
直し方
1. どこで切れているかを上から順に確かめる
原因の切り分けは、外側から順に潰すのが最短です。
インターネットに出られるか
ping 8.8.8.8
macOS / Linux
nslookup api.anthropic.com
curl -sS -o /dev/null -w '%{http_code}\n' https://api.anthropic.com/
Windows（PowerShell）
Resolve-DnsName api.anthropic.com | Select-Object Name, Type, IPAddress
Test-NetConnection api.anthropic.com -Port 443 | Select-Object ComputerName, TcpTestSucceeded
結果の読み方は次のとおりです。
| 症状 | 原因 | 進む先 |
|---|---|---|
ping が通らない |
ネットワーク未接続 | 回線・Wi-Fi を確認 |
| 名前解決が失敗する | DNS | 手順 2 |
| 名前解決はできるが 443 に繋がらない | ファイアウォール／プロキシ | 手順 3 |
| 443 は繋がるが Claude Code だけ失敗 | プロキシ設定または証明書 | 手順 3・4 |
2. DNS を疑う（ENOTFOUND）
社内DNSが外部ドメインを引けない設定になっていることがあります。公開DNSで引けるか比べてください。
macOS / Linux
nslookup api.anthropic.com 8.8.8.8
Windows（PowerShell）
Resolve-DnsName api.anthropic.com -Server 8.8.8.8
公開DNSでは引けて社内DNSでは引けないなら、DNS 側の問題です。管理者に確認してください。
VPN 接続中だけ失敗する場合は、VPN が DNS を専有している可能性があります。VPN を切って再試行し、切り分けます。
3. プロキシの設定を確認する
Claude Code は標準的なプロキシ環境変数を見ます。
macOS / Linux
env | grep -i proxy
Windows（PowerShell）
Get-ChildItem Env: | Where-Object Name -match 'proxy'
⚠️ よくある間違いが3つあります。
| 間違い | 正しい形 |
|---|---|
HTTPS_PROXY=https://proxy:8080 |
http:// で書く。プロキシへの接続自体は平文が普通 |
| 大文字と小文字が混在している | HTTP_PROXY と HTTPS_PROXY の両方を設定する |
NO_PROXY に社内ドメインしか入っていない |
除外が必要なホストを漏らさない |
設定例です。
export HTTP_PROXY=http://proxy.example.co.jp:8080
export HTTPS_PROXY=http://proxy.example.co.jp:8080
export NO_PROXY=localhost,127.0.0.1,.example.co.jp
認証が必要なプロキシの場合は、URL に含めます。⚠️ パスワードに記号が含まれるときは URL エンコードが必要です。
export HTTPS_PROXY=http://user:pa%40ss@proxy.example.co.jp:8080
（@ は %40、: は %3A、# は %23）
4. 詳細ログで確認する
claude --debug
接続先、使われたプロキシ、失敗した段階が出力されます。管理者に相談するときは、この出力を添えると話が早く済みます。
5. カスタムのベースURLを使っている場合
ゲートウェイや社内プロキシ経由で使っている場合、その設定先が生きているか確認します。
echo $ANTHROPIC_BASE_URL
設定した覚えが無いのに値が入っているなら、それが原因です。外して試してください。
unset ANTHROPIC_BASE_URL
6. 低速回線での時間切れ
回線が細くて時間切れになっている場合は、待ち時間の上限を上げます。
export API_TIMEOUT_MS=1200000
⚠️ これは「遅いが最後には届く」環境のための対処です。 そもそも到達できていない場合は延ばしても変わりません。詳しくは Request timed out を参照してください。
再発防止
- 切り分けの順序を決めておく。 ping → DNS → 443 → プロキシ → 証明書。上から潰すと迷いません
- 社内ネットワークで使うなら、プロキシ環境変数と CA 証明書をチーム共通の手順として配布する。各自が試行錯誤する時間が丸ごと消えます
- VPN 接続時だけ起きる場合は、分割トンネル（split tunnel）の対象に API のホストが入っているか管理者に確認する
--debugの出力を残しておくと、同じ現象が再発したときの比較材料になります