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

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

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

ステータス注記：2026-04-30 21:50 Asia/Shanghai 時点の Claude Status では、Claude API、Claude Code、Claude Console は operational、claude.ai は degraded performance でした。ただし 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 では次のように分けます。

hljs 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 でも同じ境界を保ちます。

hljs 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 は切り分けテストとして使う

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 全体が落ちている証明にはなりません。

変化した結果が、次に調べる 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 します。