Claude API の接続エラーを直す：ネットワーク、SDK タイムアウト、Claude Code、gateway の切り分け

Claude API で接続エラーが出たら、最初に確認するべきことは「リクエストが Anthropic まで届いたか」です。HTTP status も JSON body も request-id もないなら connection layer の問題として扱います。JSON の種類、メッセージ、request ID が返っているなら、純粋な接続エラーではなく API response の分岐に移ります。

まずこの表で分岐を選んでください。

ステータス注記：この制作時点の 2026-04-29 19:04 Asia/Shanghai では Claude API と Claude Code は operational でした。ただし status はライブ情報なので、読者は排障時点の Claude Status を必ず確認してください。古い green status だけで「原因はローカル」と断定してはいけません。

停止ルール：失敗している path を保ち、1 回の retry で変える変数は 1 つだけにします。escalation の前に timestamp、region/network、route、SDK class、HTTP status、request ID、same-path retry の結果を残します。

request ID の境界から始める

日本語で「Claude API 接続エラー」と検索する読者は、単に API error 一覧を読みたいのではありません。いま動かない呼び出しが network、VPN、firewall、SDK timeout、Claude Code の route/auth、gateway、または返却済み API error のどこに属するのかを早く知りたい状態です。最初の価値は背景説明ではなく、到達したかどうかの境界です。

Claude Help Center の connection error 記事は、firewall、network restrictions、VPN を最初の確認対象にしています。一方、Claude API Errors docsは、API が返したエラーを error.type、error.message、request_id、request-id header で扱います。この 2 つを混ぜないことが復旧の近道です。

レスポンスがないなら、次の証拠は DNS、TLS、proxy、VPN、firewall、corporate TLS inspection、container の CA、CI runner、serverless region、SDK timeout にあります。request ID があるなら、リクエストは API layer に触れています。そこからは status code と error type を分類します。

この境界を守ると、無駄な変更を避けられます。key rotation、plan upgrade、provider 切り替え、Claude Code の再インストールを早くやりすぎると、原因が消える場合もありますが、どの変数で直ったか分からなくなります。まず failing path を保存し、次に 1 つずつ切り分けます。

60 秒の same-path triage

最初の確認は短くて構いません。

1. Claude Status を開き、Claude API、Claude Code、Console、claude.ai のどの component かを確認する。
2. エラーに HTTP status、JSON body、request_id、request-id header があるかを見る。
3. 実際の route を特定する。direct api.anthropic.com、SDK、Claude Code、corporate proxy、VPN、gateway、provider wrapper、CI、container のどれか。
4. 1 つだけ変数を変え、同じ payload を同じ route で再実行する。例：VPN off、proxy off、別 network、timeout 延長、Claude Code auth refresh。
5. 変えたもの、変えていないもの、結果をメモする。

same-path retry は「何度か試す」とは違います。key、prompt、model、network、timeout、provider を同時に変えて成功しても、どれが原因だったかは分かりません。VPN だけを切って同じ request が成功したなら network branch です。timeout だけを伸ばして long request が通るなら timeout branch です。direct Anthropic は成功して gateway だけが失敗するなら route branch です。

Anthropic の接続確認ガイドも、valid API key で test request を送り、status code、response body、error messages を見る流れです。ticket や log に API key、顧客データ、private prompt、proxy credential を貼らないでください。必要なのは route とエラー証拠です。

Direct API：network、VPN、firewall、proxy、DNS、TLS

HTTP status も body も request ID もない場合は、まず direct API の到達性を疑います。原因は local host、office firewall、VPN exit、corporate proxy、DNS、TLS certificate、Docker image、CI runner、serverless region、あるいは upstream route かもしれません。

低リスクな確認から進めます。

• VPN を切る、または trusted direct network に変えて同じ request を 1 回だけ試す。
• home network、mobile hotspot、office network、別 region の cloud runner を比較する。
• firewall、allowlist、proxy rule が実際の endpoint を許可しているか確認する。
• 失敗している runtime から DNS と TLS handshake を確認する。別マシンの browser だけでは不十分です。
• corporate proxy が TLS を終端している場合、runtime の trust store と custom CA を確認する。

「同じ環境」で見ることが重要です。browser が help page を開けても、backend worker、Docker container、WSL、VS Code Remote、GitHub Actions、serverless function は別の DNS、proxy、certificate store を使っている可能性があります。実際に request を送る process からテストしてください。

別 network で同じ payload が成功したら、それは network branch の証拠です。すぐ「Claude が落ちている」と書かないでください。複数の独立 network と host が同時に失敗し、status や public reports も同じ方向を示すときだけ、platform-side または regional route issue の可能性が上がります。その場合も時刻付きで記録します。

SDK：APIConnectionError、timeout、returned API error

SDK の exception は、response が返ったかどうかを示す手がかりです。Python SDK docsでは APIConnectionError は API に接続できなかった場合、APIStatusError は non-2xx response が返った場合です。TypeScript SDK docsでは APIConnectionError は status なしの connection branch、timeout は APIConnectionTimeoutError として扱えます。

Python では次のように分けます。

python
import os
import anthropic

client = anthropic.Anthropic(timeout=60.0, max_retries=2)

try:
    message = client.messages.create(
        model=os.environ["ANTHROPIC_MODEL"],
        max_tokens=256,
        messages=[{"role": "user", "content": "Say hello in one sentence."}],
    )
except anthropic.APIConnectionError as exc:
    print("connection branch", type(exc).__name__, str(exc))
except anthropic.APIStatusError as exc:
    print("returned API branch", exc.status_code, exc.response.headers.get("request-id"))

TypeScript でも同じ境界を保ちます。

ts
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ timeout: 60_000, maxRetries: 2 });

try {
  const message = await client.messages.create({
    model: process.env.ANTHROPIC_MODEL!,
    max_tokens: 256,
    messages: [{ role: "user", content: "Say hello in one sentence." }],
  });
} catch (error) {
  if (error instanceof Anthropic.APIConnectionTimeoutError) {
    console.error("timeout branch", error.message);
  } else if (error instanceof Anthropic.APIConnectionError) {
    console.error("connection branch", error.message);
  } else if (error instanceof Anthropic.APIError) {
    console.error("returned API branch", error.status, error.headers?.["request-id"]);
  }
}

注意点は 2 つあります。まず、SDK の default retry は最初の失敗を隠すことがあります。最終失敗時刻、retry count、SDK version を残してください。次に、長い non-streaming request は intermediate network が idle connection を切って失敗することがあります。prompt が長い、tool call が遅い、出力が大きい場合は streaming または timeout を確認してから outage と判断します。

APIConnectionError は rate limit ではありません。HTTP status が返っているなら分岐を変えます。529 は Claude API 529 overloaded error、429 は Claude API rate-limit reached、Claude Code の 500 は Claude Code API Error 500 を確認してください。

Claude Code：terminal route、auth state、environment

Claude Code で API Error: Connection error が出ている場合、direct SDK の判断だけでは足りません。Claude Code は subscription OAuth、API key route、terminal proxy variables、WSL networking、VS Code Remote、corporate terminal proxy、provider wrapper を通ることがあります。

最初に確認する項目です。

• /status を実行し、active authentication method と route を記録する。
• Claude Code を起動した shell、IDE、WSL、container、CI に ANTHROPIC_API_KEY があるか見る。
• HTTPS_PROXY、HTTP_PROXY、NO_PROXY、custom CA を確認する。
• WSL や VS Code Remote だけで失敗するなら、local terminal と同じ command で比較する。
• route owner が分かる前に reinstall や一括 cleanup をしない。

よくある誤解は、Claude Code が常に subscription login route を使っていると思い込むことです。ANTHROPIC_API_KEY が environment にあれば、API-key route を使っている可能性があります。browser の Claude が動いていても、terminal の proxy、DNS、certificate、key route は別問題です。

route 設定が原因なら Claude Code API configuration guide へ進みます。returned error が 500/529/rate limit なら Claude Code 500/529/rate-limit router に切り替えてください。

Gateway/provider は isolation test として使う

gateway、proxy、OpenAI-compatible provider は route owner を見つけるための比較には使えます。ただし最初から万能な回避策として扱わないでください。direct Anthropic が試せるなら先に baseline を取ります。その後、同じ prompt、input size、model intent、timeout、environment のまま gateway route に変えます。

direct は成功し gateway が失敗するなら、gateway credential、model mapping、proxy、compatibility layer が疑われます。direct は失敗し gateway は成功するなら、別 route で到達できる証拠にはなりますが、公式 API 全体が落ちている証明にはなりません。

開発チームが 2 本目の API route で切り分けたい場合、laozhang.ai は gateway isolation route として使えます。この段落は狭く保ちます。speed、uptime、quota、price、refund、guarantee は本稿では検証していないため書きません。

変化した結果が、次に調べる owner です。変化しないなら、さらに範囲を狭めます。

もう connection error ではない場合

HTTP status、JSON body、request ID のいずれかがあるなら、request は API layer に届いています。ここからは request ID を保存し、returned error として分類します。

returned 429 を connection error と呼び続けると、修復がずれます。429 は rate-limit handling、529 は overload-aware retry、500 は別の incident/escalation evidence、DNS failure は local network branch です。

escalation 用の最小 evidence packet

status、request-id boundary、route owner、same-path retry を確認しても同じ path が失敗する場合に escalation します。必要なのは長文ではなく、branch が分かる証拠です。

集めるもの：

• timestamp と timezone。
• SDK name、SDK version、runtime、host、region。
• exact error string と exception class。
• あれば HTTP status、error.type、error.message、request ID。
• active route：direct Anthropic、Claude Code、gateway、proxy、VPN、CI、WSL、container、browser。
• その時点の Claude Status。
• 1 つの変数を変えた same-path retry result。
• secrets を抜いた最小 reproduction。

API key、private prompt、customer data、credential 付き proxy log、完全な request body は送らないでください。support に必要なのは「どの branch を試し、同じ failure がどう残ったか」です。

よくある質問

Claude API の接続エラーは何を意味しますか？

status code、JSON body、request ID がない場合、client が API までの route を完了できなかった可能性があります。status、network、VPN、firewall、proxy、DNS/TLS、SDK timeout、route ownership を確認します。

まず API key を変えるべきですか？

通常は違います。no-response connection error では、key rotation より先に到達性と route を確認します。auth や key owner の証拠が出たときだけ credential を扱います。

Claude Status が green ならローカル原因ですか？

断定できません。green status は live incident の可能性を下げるだけです。local network、SDK、Claude Code route、gateway、regional path は別に壊れている可能性があります。

SDK が APIConnectionError を出すのに HTTP status がないのはなぜですか？

SDK が通常の API response を受け取っていないためです。connectivity、proxy、DNS/TLS、VPN、firewall、timeout、route を見てください。

Claude Code の API Error: Connection error も同じですか？

request ID の境界は同じですが、Claude Code では /status、ANTHROPIC_API_KEY、terminal proxy、WSL、VS Code、auth route も確認します。

gateway route はいつ使いますか？

direct access が blocked のとき、または compatible route を比較したいときです。prompt、input size、model intent、timeout を固定し、route だけを変えます。

support には何を送りますか？

timestamp、route、SDK/runtime、exact error、HTTP status、request ID、status page note、same-path retry result、redacted reproduction を送ります。branch が明確な evidence の方が役に立ちます。

実務ルール

Claude API の接続エラーは、response が返るまでは reachability problem として扱います。現在の status を確認し、request-id boundary を保ち、direct API、SDK、Claude Code、network/proxy、gateway branch を選び、1 つだけ変数を変えて同じ path を再試行します。まだ失敗する場合だけ、最小 evidence packet で escalation します。