Claude API: ошибка подключения. Как проверить сеть, SDK, Claude Code и gateway-маршрут

Если Claude API показывает ошибку подключения, сначала докажите, дошел ли запрос до Anthropic. Нет HTTP-статуса, нет JSON-тела и нет request-id - это ветка соединения; если вернулся JSON с типом, сообщением и request ID, это уже ветка ответа API, а не чистая проблема сети.

Начните с этого разделения:

Примечание о статусе: 2026-04-30 21:50 Asia/Shanghai Claude Status показывал operational для Claude API, Claude Code и Claude Console, а claude.ai - degraded performance. Статус меняется в реальном времени, поэтому читатель должен проверить актуальную страницу перед выводом, что проблема локальная.

Стоп-правило: сохраните failing path, меняйте только одну переменную за retry и до escalation соберите timestamp, region/network, route, SDK class, HTTP status, request ID и результат same-path retry.

Начните с границы request ID

Русскоязычная выдача по запросу "Claude API ошибка подключения" сразу показывает официальный Help Center, Reddit с реальными жалобами, Claude Code docs и GitHub issues. Это полезный сигнал: пользователю нужен не общий справочник по API errors, а быстрая классификация, где именно обрывается путь. Одни проблемы живут в локальной сети или VPN, другие в SDK timeout, третьи в Claude Code auth route, четвертые в gateway/provider слое.

Статья Claude Help Center об API connection error направляет первую проверку к firewall, network restrictions и VPN. Документация Claude API Errors задает другую границу: returned errors имеют error.type, error.message, request_id, а ответы API включают request-id header. Эти два факта достаточно строгие, чтобы выбрать ветку.

Если ответа нет, смотрите connectivity: DNS, TLS, proxy, VPN, firewall, corporate inspection, runtime trust store, container или CI network. Если request ID есть, запрос уже дошел до API layer. Тогда не надо продолжать включать и выключать VPN; надо классифицировать returned status.

Такой подход сохраняет диагностический сигнал. Смена API key, provider, plan, model, proxy и machine одновременно может случайно убрать ошибку, но не объяснит причину. Сначала сохраните маршрут, затем меняйте одну переменную.

Same-path triage за 60 секунд

Быстрый порядок такой:

1. Откройте Claude Status и выберите компонент: Claude API, Claude Code, Console или claude.ai.
2. Найдите HTTP status, JSON body, request_id или request-id header.
3. Определите фактический route: direct api.anthropic.com, SDK, Claude Code, корпоративный proxy, VPN, gateway, provider wrapper, CI или container.
4. Повторите тот же payload после одного изменения: VPN off, proxy off, другая сеть, longer timeout, fresh Claude Code auth state.
5. Зафиксируйте, что изменилось и что осталось тем же.

Same-path retry важнее, чем "попробуйте еще раз". Если вы одновременно меняете key, prompt, model, network, timeout и provider, успешный результат не говорит, какая переменная помогла. Если та же просьба работает после отключения VPN, это network branch. Если long non-streaming request работает после увеличения timeout, это timeout branch. Если direct Anthropic работает, а gateway падает, это route branch.

Anthropic также описывает connectivity check: валидный API key, test request, затем status code, response body и error messages. Не копируйте секреты в тикеты. Нужны route, timestamp, error class и результат повторной проверки, а не полный private prompt.

Direct API: network, VPN, firewall, proxy, DNS и TLS

Эта ветка нужна, когда нет HTTP status, нет body и нет request ID. Владелец проблемы может быть в локальном host, office firewall, VPN exit, corporate proxy, DNS, TLS certificate, Docker image, CI runner, serverless region или upstream route.

Начните с минимально разрушительных тестов:

• Отключите VPN или смените VPN на доверенную прямую сеть для одного retry.
• Сравните home network, mobile hotspot, office network и cloud runner в другом region.
• Проверьте, разрешены ли endpoint и TLS handshake в firewall, allowlist и proxy.
• Запустите DNS/TLS test из той же среды, где падает request, а не из браузера на другой машине.
• Если корпоративный proxy перехватывает TLS, проверьте CA trust store в runtime.

"Та же среда" - ключевой критерий. Browser может открывать help page, но backend worker, container, WSL, VS Code Remote или GitHub Actions могут иметь другой DNS, proxy и trust store. Проверка должна происходить там, где реально отправляется API call.

Если другой network path исправляет тот же payload, не делайте вывод "Claude down". Запишите network branch. Если несколько независимых сетей и host одновременно падают, а status или публичные reports тоже шумят, тогда platform-side или regional route issue становится вероятнее, но вывод должен быть датирован.

SDK: APIConnectionError, timeout и returned API errors

SDK exception помогает понять, есть ли response. В Python SDK docs APIConnectionError означает, что library не смогла подключиться к API, а APIStatusError означает non-2xx response. В TypeScript SDK docs APIConnectionError относится к ветке без HTTP status, а 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"]);
  }
}

Две детали часто теряются. SDK retry может скрыть первую попытку, поэтому сохраняйте final failure time, retry count и SDK version. Long non-streaming requests иногда падают из-за idle connection drop в промежуточной сети; перед выводом "сервис сломан" проверьте streaming, timeout и размер ответа.

APIConnectionError не является rate limit. Если SDK вернул 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, проверяйте не только Anthropic API. Claude Code может использовать subscription OAuth, API key route, inherited proxy variables, WSL networking, VS Code Remote, корпоративный terminal proxy или provider wrapper.

Порядок проверки:

• Выполните /status и запишите активный auth method и route.
• Проверьте, установлен ли ANTHROPIC_API_KEY в shell, IDE, WSL, container или CI.
• Сравните HTTPS_PROXY, HTTP_PROXY, NO_PROXY и custom CA.
• Если ошибка только в WSL или VS Code Remote, повторите ту же команду в local terminal.
• Не переустанавливайте инструмент до понимания route owner.

Ловушка проста: пользователь думает, что Claude Code идет по subscription login, а terminal фактически отправляет API-key request. Или браузер работает, но terminal унаследовал proxy, который ломает TLS. /status нужен рано, потому что он разделяет предполагаемый и фактический маршрут.

Если проблема в настройке маршрута, используйте Claude Code API configuration guide. Если выяснилось, что returned branch - это 500/529/rate limit в Claude Code, переходите к Claude Code 500/529/rate-limit router.

Gateway или provider: изоляционный тест, не универсальная замена

Gateway, proxy или OpenAI-compatible provider может помочь понять route owner, но не должен быть первой догадкой. Если direct Anthropic доступен, сначала проверьте его. Затем сравните gateway route с тем же prompt, input size, model intent, timeout и environment. Direct работает, gateway падает - вероятен gateway, credential, model mapping или compatibility layer. Direct падает, gateway работает - это доказательство альтернативного маршрута, а не доказательство, что официальный сервис полностью недоступен.

Чистый тест:

Если результат меняется, вы нашли следующую переменную. Если нет, продолжайте сужать область.

Когда это уже не connection error

Как только появился HTTP status или JSON body с error.type, запрос достиг API layer. Сохраните request ID и классифицируйте returned error.

Не продолжайте называть 429 или 529 "ошибкой подключения". Это разные задачи. 429 требует rate-limit handling, 529 - overload-aware retry, 500 - другой escalation packet, а локальный DNS failure - совсем другая ветка.

Evidence packet для escalation

Escalation нужна после проверки status, request-id boundary, route owner и одного same-path retry. Пакет должен быть коротким, но пригодным для routing.

Соберите:

• 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;
• результат same-path retry после одного изменения;
• redacted reproduction без ключей и приватных данных.

Не отправляйте API keys, private prompts, customer records, proxy logs with credentials или полный request body. Хороший escalation message не длинный, а однозначный: какая ветка проверена и какой результат повторился.

Часто задаваемые вопросы

Что обычно означает Claude API connection error?

Если нет status code, body и request ID, это чаще всего reachability branch. Проверьте статус, network, VPN, firewall, proxy, DNS/TLS, SDK timeout и фактический route.

Нужно ли сначала менять API key?

Обычно нет. Key rotation - плохой первый шаг для no-response connection error. Сначала докажите, дошел ли request до API, и повторите тот же путь после одного route или network change.

Зеленый Claude Status доказывает локальную проблему?

Нет. Он только снижает вероятность live incident на выбранном component. Локальный route, SDK, Claude Code environment, gateway и региональная сеть все еще могут быть broken.

Почему SDK показывает APIConnectionError, но нет HTTP status?

Потому что SDK не получил обычный API response. Это сигнал смотреть connectivity, proxy, DNS/TLS, VPN, firewall, timeout и route ownership.

API Error: Connection error в Claude Code - то же самое?

Граница request ID та же, но Claude Code добавляет /status, ANTHROPIC_API_KEY, terminal proxy, WSL, VS Code и auth route.

Когда использовать gateway route?

Когда direct access blocked или нужен второй compatible route для диагностики. Сравнивайте controlled: тот же 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. Это лучше, чем общий текст "Claude не работает".

Рабочее правило

Claude API connection error остается reachability problem, пока запрос не дал response. Проверьте live status, сохраните request-id boundary, выберите direct API, SDK, Claude Code, network/proxy или gateway branch, меняйте одну переменную, повторяйте тот же путь и escalatе только с минимальным evidence packet.