Claude API connection errorが出たときの切り分けと疎通確認

API connection errorは「応答が返る前」の失敗

API connection errorは、Claude APIからHTTPの応答を受け取る前に通信が成立しなかったときのエラーです。サポート記事は、このエラーの多くが手元のファイアウォール・ネットワーク・VPNに起因すると案内しています。Anthropic側の障害を疑う前に、自分の経路を確かめる順序です。

SDKの側から見ると、この種の失敗は APIConnectionError として現れます。公式SDKの対応表では、HTTPステータスコードを持つ400・401・429・500以上のエラーと違い、ステータスコードの欄が「N/A」です。ステータスが無い。つまりサーバーから何も返っていません。

この違いが切り分けの出発点になります。

ステータスコードが付いたエラーは、通信自体は届いています。この記事が扱うのは一番上の行だけです。ステータスごとの対処はエラーハンドリングの記事にまとめています(Claude APIのエラーハンドリング設計)。

サポート記事が挙げる3つの対処

サポート記事の対処は3項目です。

1. ファイアウォールやネットワーク制限が、Claude APIのエンドポイントへの接続を塞いでいないか確認する
2. ファイアウォールやネットワーク設定を、その接続を許可する内容に直す
3. リクエストを送る間はVPNを使わない

解決しない場合は、ヘルプセンター右下のメッセージアイコン、またはConsoleの左下にある自分のイニシャルから「Get help」でサポートに連絡します。

順番は「VPNを外す → ネットワーク制限を疑う → 許可設定を入れる」が試しやすい並びです。VPNは切り替えるだけで結果が変わるので、最初の切り分けに向いています。以降の節で、それぞれの確かめ方を具体的に書きます。

手順1: 最小のリクエストで疎通を確かめる

アプリケーションのコードを疑う前に、同じマシン・同じネットワークから最小のリクエストを直接送ります。サポート記事の疎通確認は次の3段階です。

1. Consoleにログインして、APIキーを作成する
2. そのキーでテストリクエストを送る(公式のGetting startedに例がある)
3. レスポンスのステータスコード・本文・エラーメッセージで成否を確かめる

Getting startedのcURLの例をもとにした確認コマンドは、次の形になります。通常のメッセージ作成リクエストなので、ごく小さくてもトークン課金は発生します。max_tokens を小さく絞ってあります。

export ANTHROPIC_API_KEY="sk-ant-..."   # Consoleで作成したキー
 
curl -sS -m 15 https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "ping"}]
  }' -i

-m 15 は15秒で打ち切る指定、-i はレスポンスヘッダーも表示する指定です。結果は次のように読みます。

• JSONが返る: ステータスがいくつでも、Claude APIまで通信は届いています。この経路の接続に問題はありません。401が返ったならキーの問題、200ならその環境では正常です
• 接続エラーで終わる: 名前解決の失敗、接続拒否、タイムアウトなど、curl自身がメッセージを出して終了します。応答が返っていないので、経路上の遮断を疑います
• プロキシ由来のHTML(認証画面やブロック通知)が返る: 社内プロキシやセキュリティ製品が途中で応答している状態です。ヘッダーに request-id が無いなら、Claude APIには届いていません

最後の判定は、公式の「エラー応答には request-id ヘッダーが必ず付く」という仕様に基づく切り分けです。Claude APIが返した応答であれば、成功でも失敗でもヘッダーにこのIDが入ります。

手順2: SDKで同じ確認を再現する

curlは通るのにアプリだけ失敗するなら、差はSDK側の設定にあります。Pythonの場合、接続失敗を別の例外として受け、原因を出力する確認スクリプトが使えます。

import anthropic
 
client = anthropic.Anthropic(max_retries=0, timeout=15.0)
 
try:
    message = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=16,
        messages=[{"role": "user", "content": "ping"}],
    )
    print("OK", message._request_id)
except anthropic.APIConnectionError as e:
    print("届いていない:", e.__cause__)
except anthropic.APIStatusError as e:
    print("届いた:", e.status_code)

ポイントは2つです。

• max_retries=0: SDKは接続エラーを既定で2回、短い指数バックオフで自動的に再試行します。診断のときは再試行を切ると、失敗が即座に見えます
• e.__cause__: ドキュメントの例でも、APIConnectionError の原因になった例外を __cause__ から取り出しています。名前解決の失敗か、接続拒否か、TLSの問題かは、ここに出ます

APIStatusError の側に入れば通信は届いています。message._request_id は、成功時のレスポンスから取り出せるリクエストIDです。サポートへ問い合わせるときはこのIDが手掛かりになります。例外クラスの言語別の対応はClaude APIのエラー形式とSDK例外クラスの言語別対応表に整理しています。

手順3: VPNを外して比べる

curlも失敗するなら、経路そのものを疑います。最初に試すのはVPNです。

VPNを切ったネットワーク(自宅回線やテザリングなど)で、手順1のコマンドをそのまま実行します。VPNを切ると通る場合は、VPNの出口側かVPN経由の社内プロキシが api.anthropic.com への通信を止めています。サポート記事も「リクエストを送る間はVPNを使わない」ことを対処に挙げています。

VPNが必須の環境では、VPN管理者にClaude APIの宛先を通すよう依頼する形になります。宛先の指定方法は次の手順に続きます。

手順4: ファイアウォールに許可を入れる

VPNを外しても失敗する、あるいはVPNを外せない企業ネットワークでは、ファイアウォールの許可設定を確認します。公式のIPアドレスのページには、Claude APIへ接続する際の宛先(inbound)として、次のレンジが載っています。

ここで押さえておく点は3つです。

• ポートは標準のHTTPS(443)です。アドレスだけでなくプロトコルとポートも許可ルールに含めます
• IPv6のレンジもあります。IPv4だけを許可しているルールセットでは、IPv6で解決された接続だけが落ちる状況が起こり得ます
• AWS上のClaude Platformを使う場合、inboundの宛先はAWS側のIPレンジに解決されます。ここに挙げたレンジは当てはまりません

宛先が正しいレンジに解決されているかの確認や、削除しておきたい旧IPアドレスの一覧、outboundとの区別は、別記事で詳しく書いています(Claude APIのIPアドレスをファイアウォールに許可登録する手順)。

手順5: プロキシ経由の環境ではSDKに設定を渡す

社内プロキシを通す環境では、curlはプロキシ設定に従うのにSDKは従わない、という食い違いが出ることがあります。公式のSDKドキュメントは、HTTPクライアントを差し替えてプロキシを指定する方法を示しています。

Pythonでは、DefaultHttpxClient にプロキシを渡します。

import anthropic
from anthropic import DefaultHttpxClient
 
client = anthropic.Anthropic(
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
    ),
)

TypeScriptでは、Node.jsの場合に undici の ProxyAgent を fetchOptions の dispatcher に渡します。

import Anthropic from "@anthropic-ai/sdk";
import * as undici from "undici";
 
const proxyAgent = new undici.ProxyAgent("http://localhost:8888");
const client = new Anthropic({
  fetchOptions: { dispatcher: proxyAgent },
});

プロキシのURLは自分の環境の値に置き換えます。認証付きプロキシの書式などは公式ドキュメントに例が無いため、社内のプロキシ管理者に確認します。

長い非ストリーミング要求は別の原因で切れる

接続自体は成立するのに、長い処理の途中で切れる型もあります。公式ドキュメントによると、ネットワークによっては一定時間で待機中の接続を切ります。max_tokens を大きく取った非ストリーミングのリクエストは、応答が返るまで接続が無通信の時間が長く、この影響を受けやすい構成です。

対策は3つあります。

• ストリーミングのMessages APIを使う。イベントが流れ続けるので接続が無通信にならない
• 途中経過が不要なら、SDKにストリームを消費させて完成した Message だけ受け取る
• 長時間かかる処理はMessage Batches APIに回し、結果をポーリングで受け取る

SDKは非ストリーミングの要求が約10分を超えそうなときにエラーで知らせます。TCPのキープアライブも既定で設定します。ストリーミングの復旧の挙動は、別記事にあります(Claude APIストリーミングのエラー復旧がv4.6で変わった)。

切り分けの早見表

ここまでの手順を、症状から試す順に並べ直します。

直らないときに手元へ残す情報

上の手順で直らないときは、サポートへの問い合わせ用に次を控えます。

• 手順1のcurlの出力(ヘッダー込み)
• 失敗したSDKの e.__cause__ の内容
• 成功したリクエストがあれば、その request-id
• VPNの有無、プロキシの有無、実行しているマシンの種類(自宅端末・社内サーバー・CIなど)

ドキュメントは、特定のリクエストについて問い合わせるときにリクエストIDを添えるよう案内しています。ただし接続エラーの場合、サーバーまで届いていないため、失敗したリクエスト自体にIDはありません。手元の環境情報のほうが手掛かりになります。

まとめ

API connection errorは、HTTPの応答が返る前に通信が途切れた状態を指します。サポート記事の対処は、ネットワーク制限の確認・許可設定・VPNの回避の3つです。

切り分けは、実際にAPIを呼ぶマシンから最小のリクエストを送るところから始めます。JSONが返ればClaude APIまで届いているので、ステータスに応じた対処へ進みます。届いていなければ、VPNを外した回線での再実行、許可レンジの登録、SDKへのプロキシ指定の順に絞ります。