ストアの説明文の翻訳を下書きさせる小さな Python スクリプトを、夜に流していたときのことです。昨日まで動いていたのに、その晩だけ anthropic.APIConnectionError: Connection error. の一行で止まりました。
私は最初、API キーを疑いました。キーを作り直し、環境変数を読み直し、30分ほど同じところを回っておりました。原因は、昼間に試した VPN アプリが残していたプロキシの設定で、キーとは何の関係もありませんでした。
いま思えば、遠回りの理由ははっきりしています。「Connection error.」という文言は、原因を何も教えてくれていなかったのです。結論を先にお伝えすると——答えは例外の外側ではなく、奥に入っています。
「Connection error.」は4つの別の失敗を同じ顔で見せます
まず、同じ文言がどこまで別の原因を覆い隠すのかを、手元で確かめました。SDK は anthropic 2.11.0、Python 3.10 の Linux 環境で、わざと4種類の失敗を起こしています。
| 起こした状況 | 例外の文言 | いちばん奥の例外 |
|---|---|---|
| base_url の綴りを間違えた | Connection error. | socket.gaierror: Name or service not known |
| 存在しないプロキシを HTTPS_PROXY に設定 | Connection error. | ConnectionRefusedError: Connection refused |
| 別の CA だけを SSL_CERT_FILE に指定 | Connection error. | ssl.SSLCertVerificationError: CERTIFICATE_VERIFY_FAILED |
| timeout を極端に短くした | Request timed out or interrupted. … | TimeoutError: timed out |
上の3つは、メッセージが一字一句同じでした。4つ目だけ文言が違いますが、anthropic.APITimeoutError は APIConnectionError の子クラスです。except anthropic.APIConnectionError と書いていると、時間切れも同じ枝に落ちてきます。
もう一つ、予想と違ったことがあります。プロキシが原因のときも、奥の例外は「Connection refused」としか言わず、プロキシという言葉は一度も出てきませんでした。断ったのは api.anthropic.com ではなく手元のプロキシなのに、表示だけを見ると Anthropic 側に断られたように読めてしまいます。
例外の奥を辿る診断スクリプト
SDK は、下の層で起きた例外を __cause__ に繋いだまま APIConnectionError を投げています。手元の版では3段で、httpx2.ConnectError → httpcore2.ConnectError → 標準ライブラリの例外、という並びでした(版によっては httpx の名前で表示されます)。
次のスクリプトは、その鎖を最後まで辿り、いちばん奥の例外の型で原因を4つに振り分けます。何を解決するかというと、「Connection error.」を見た瞬間に、キー・回線・証明書・プロキシのどこから見ればよいかを1回の実行で決められるようにするためです。
import os
import socket
import ssl
import anthropic
PROXY_VARS = ("HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy")
def cause_chain(exc):
"""APIConnectionError の奥にある例外を、外側から順に並べる"""
chain, seen = [], set()
cur = exc.__cause__ or exc.__context__
while cur is not None and id(cur) not in seen:
seen.add(id(cur))
chain.append(cur)
cur = cur.__cause__ or cur.__context__
return chain
def classify(exc):
chain = cause_chain(exc)
root = chain[-1] if chain else exc
proxy = next((os.environ[v] for v in PROXY_VARS if os.environ.get(v)), None)
if isinstance(exc, anthropic.APITimeoutError) or isinstance(root, TimeoutError):
return "timeout", "時間切れ。timeout の値と、回線・VPN の遅さを先に見る"
if isinstance(root, ssl.SSLCertVerificationError):
hint = os.environ.get("SSL_CERT_FILE") or "(未設定)"
return "certificate", f"証明書の検証で失敗。SSL_CERT_FILE={hint}・社内の中継装置を疑う"
if isinstance(root, socket.gaierror):
return "dns", "名前解決で失敗。base_url の綴りと DNS を見る"
if isinstance(root, ConnectionRefusedError) and proxy:
return "proxy", f"接続を断られた。相手は api.anthropic.com ではなくプロキシ {proxy} の可能性"
if isinstance(root, ConnectionRefusedError):
return "refused", "接続を断られた。base_url のポートとゲートウェイの起動状態を見る"
return "unknown", f"未分類: {type(root).__module__}.{type(root).__name__}: {root}"
def call(client):
try:
return client.messages.create(
model="claude-haiku-4-5-20251001",
max_tokens=16,
messages=[{"role": "user", "content": "ping"}],
)
except anthropic.APIConnectionError as e:
kind, hint = classify(e)
print(f"[{kind}] {type(e).__name__}: {e}")
for c in cause_chain(e):
print(f" <- {type(c).__module__}.{type(c).__name__}: {str(c)[:90]}")
print(f" => {hint}")
raise
if __name__ == "__main__":
client = anthropic.Anthropic(
api_key=os.environ.get("ANTHROPIC_API_KEY", "YOUR_API_KEY"),
base_url=os.environ.get("ANTHROPIC_BASE_URL") or None,
max_retries=0, # 切り分け中は再送させない(原因が1回で見える)
)
try:
call(client)
except anthropic.APIConnectionError:
pass
except anthropic.APIStatusError as e:
print(f"[reached] HTTP {e.status_code} が返った=接続は通っている")why_connection_error.py として保存し、ふだんと同じ環境変数のまま実行します。プロキシを残した状態で流したときの出力は、次のとおりでした。
$ HTTPS_PROXY=http://127.0.0.1:9 python3 why_connection_error.py
[proxy] APIConnectionError: Connection error.
<- httpx2.ConnectError: [Errno 111] Connection refused
<- httpcore2.ConnectError: [Errno 111] Connection refused
<- builtins.ConnectionRefusedError: [Errno 111] Connection refused
=> 接続を断られた。相手は api.anthropic.com ではなくプロキシ http://127.0.0.1:9 の可能性なぜこう書くのかを、三つだけ補足します。
max_retries=0で切り分ける理由: 既定の SDK は接続失敗を2回まで再送します。名前解決の失敗で比べると、再送なしは0.0秒、既定のままでは1.4秒待ってから同じ一行が出ました。原因を見たいときに待つ意味はありません- 鎖の最後を見る理由: 途中の
ConnectErrorはどれも同じ型で、区別の手がかりは標準ライブラリの例外にしか残っていません - わざと 401 を受ける理由: キーが仮の値でも、
[reached] HTTP 401が返れば接続そのものは通っています。キーの問題と回線の問題を、ここで初めて切り離せます
4つの原因ごとの直し方
振り分けが済めば、直し方はそれぞれ短く済みます。私は次の順で手を動かしております。
dns(名前解決の失敗)
ANTHROPIC_BASE_URL のホスト名の綴りと、社内 DNS が外部ドメインを引けるかを確かめます。python3 -c "import socket; print(socket.getaddrinfo('api.anthropic.com', 443)[0][4])" が IP を返すなら、DNS ではなく base_url 側の問題です。
proxy(プロキシに断られた)
まず env | grep -i proxy で、自分が設定した覚えのない値が残っていないかを見ます。私の場合、原因はこれでした。プロキシを通す必要がない環境なら変数を外し、通す必要があるなら NO_PROXY=api.anthropic.com で api.anthropic.com だけを除外します。手元でも、同じ壊れたプロキシを残したまま NO_PROXY を足すと、すぐに 401 が返ってくるようになりました。
certificate(証明書の検証に失敗)
社内の中継装置が通信を開いて検査している環境では、その装置の CA を信頼させる必要があります。装置の CA と標準の CA をまとめたファイルを作り、SSL_CERT_FILE に渡すのが手堅い方法です。
ここで一つ、つまずきやすい点があります。SSL_CERT_FILE に空のファイルを指定したところ、リクエストの時点ではなく、クライアントを作った瞬間に ssl.SSLError が出ました。これは APIConnectionError ではないので、上のスクリプトの except にも掛かりません。verify=False で黙らせる方向へは進まず、渡しているファイルの中身を確かめてください。
timeout(時間切れ)
既定の接続タイムアウトは5秒、読み込みは600秒でした。接続の段階で切れているなら回線や VPN を、応答の途中で切れているなら長い出力の扱いを見直します。長い応答の時間切れと自動再送が重なると、知らないうちに二重に課金されることがあります。その仕組みと設計の直し方は、非ストリーミングの長い応答が10分の壁で黙って二重課金されていたに詳しく書き残しました。
本番のコードに残す、1行の印
切り分けのスクリプトは手元で使えば十分ですが、本番のログにも原因の印だけは残すようにしました。送信を包む関数の except で、classify(e) の結果をログの項目に1つ足すだけです。
import logging
import anthropic
from why_connection_error import classify
logger = logging.getLogger("claude")
def send(client, **params):
try:
return client.messages.create(**params)
except anthropic.APIConnectionError as e:
kind, _ = classify(e)
logger.warning("claude_connection_error", extra={"kind": kind, "retries": client.max_retries})
raiseこれだけで、翌朝ログを見返したときに「dns が3件、timeout が1件」と数えられるようになります。以前の私は、同じ「Connection error.」が並ぶログを前に、どれが同じ原因なのかを判断できずに手が止まっていました。
例外の名前ではなく、いちばん奥の一行で判断します。 個人開発で一人きりで回しているスクリプトだからこそ、再送の回数を増やすのは、原因が時間切れだと分かってからにしています。再送そのものの設計は、retry-after が 120 秒の 429 を受けたときの記録で別に扱いました。
直らないときの次の一手
4つのどれにも当てはまらず unknown が出たときは、同じ端末から curl -sv https://api.anthropic.com/v1/messages -o /dev/null を一度だけ実行し、TLS のやり取りがどこで止まるかを見ます。curl では通るのに Python だけ失敗するなら、Python 側が読んでいる証明書と環境変数の違いに絞り込めます。
それでも分からないときは、[unknown] の行をそのまま添えて、ゲートウェイの管理者や回線の担当の方に相談するのが近道です。「Connection error. が出ます」と伝えるより、「奥の例外は〇〇です」と伝えたほうが、相手の手もずっと早く動きます。
まずは今夜、いつもの環境変数のまま why_connection_error.py を一度だけ流し、[reached] が出ることを確かめておいていただければと思います。何も起きていないうちに一度通しておくと、次に止まった夜の自分がずいぶん助かります。