◉CLAUDE LABEN
●CC 2.1.328 — Claude Code 2.1.328(11/19)で、予約タスクを保存したときにほかのタスクが消えることがある問題が直りました●SONNET 4.5 — Claude API での提供終了は 11/30、残り10日。コードと保存済みのモデル設定を一度に洗い出してください●USAGE — 11/9 の週から、使用量の上限が以前の3〜5倍の速さで尽きる、という報告が出ています●NEW — Claude Code と Gemini CLI の MCP 設定は一つの正本から●GEMINI API — Gemini API にも、道具の定義を必要なときだけ読み込む tool retrieval(Preview)が入りました●CREDIT — Credit balance が足りないと出たら、まずどの請求先の残高かを確かめると早く片づきます●CC 2.1.328 — Claude Code 2.1.328(11/19)で、予約タスクを保存したときにほかのタスクが消えることがある問題が直りました●SONNET 4.5 — Claude API での提供終了は 11/30、残り10日。コードと保存済みのモデル設定を一度に洗い出してください●USAGE — 11/9 の週から、使用量の上限が以前の3〜5倍の速さで尽きる、という報告が出ています●NEW — Claude Code と Gemini CLI の MCP 設定は一つの正本から●GEMINI API — Gemini API にも、道具の定義を必要なときだけ読み込む tool retrieval(Preview)が入りました●CREDIT — Credit balance が足りないと出たら、まずどの請求先の残高かを確かめると早く片づきます
記事一覧/API & SDK
⬡ API & SDK/2026-11-20中級

Claude API が「Connection error.」としか言わないとき、例外の奥を3段たどって原因を4つに分けます

Python SDK の APIConnectionError は、DNS・プロキシ・証明書・時間切れのどれでも同じ「Connection error.」を返します。__cause__ を辿る診断スクリプトと、手元で4種類を再現した実際の出力、直し方の順番をまとめました。

claude-api84python-sdkAPIConnectionErrorproxyssltroubleshooting64

ストアの説明文の翻訳を下書きさせる小さな 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] が出ることを確かめておいていただければと思います。何も起きていないうちに一度通しておくと、次に止まった夜の自分がずいぶん助かります。

シェア

お読みいただきありがとうございます

Claude Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

もしこの記事がお役に立ちましたら、チップ(¥150)で応援いただけると大変励みになります。広告なしでの運営を続けるため、皆さまのご支援が大きな力になっています。

関連記事

⬡ API & SDK2026-05-22
Claude の『このモデルは現在利用できません』が出る時に効くモデル選択フォールバックの設計
Claude API で『このモデルは現在利用できません』が返ったとき、529 や 429 と同じ扱いにすると遠回りになります。11 月 30 日の Sonnet 4.5 退役を前に、Models API でモデルの寿命と thinking の対応を起動時に確かめ、例外クラスで拒否を見分けてモデルを切り替えるフォールバックの実装と、代役で 400 になる落とし穴をまとめました。
⬡ API & SDK2026-10-24
「Credit balance is too low」の前に見る3つの勘定 — 含まれるクレジットと購入分は別の財布です
Max や Team の API クレジットが残っているはずなのに「Credit balance is too low」と出る。原因は、含まれるクレジットの対象外の呼び出しと、購入分の残高、月間上限が別々に動いているためです。Console で見る順番と、夜間スクリプトに入れる検知コードをまとめました。
⬡ API & SDK2026-09-22
PDF の入力トークンは文字数では読めません — 送る前にページ数から上限で挟む
Claude API に PDF を送る前の入力トークンを、文字数ではなくページ数から上限で挟んで見積もる手順です。A4 9 ページの日本語文書で文字数見積もりの 6.6 倍になった実測と、解像度ティアとトークナイザの二重の増分、count_tokens が file_id を数えられない制約までをまとめます。