# Claude Code: Unable to connect to API — как исправить ECONNREFUSED, ECONNRESET и proxy

> Проверьте API host из shell, который запускает Claude Code, и исправляйте только ветку, указанную результатом: сеть, proxy, CA, среду или gateway.

- URL: https://blog.laozhang.ai/ru/posts/claude-api-error-connection-error
- Published: 2026-08-04
- Updated: 2026-08-04
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ru/about)
- Topic: Claude Code
- Tags: Claude Code, Unable to connect to API, ECONNRESET, Proxy, Диагностика

---
Сообщение `Unable to connect to API` означает, что Claude Code не завершил TCP-соединение с текущим API-маршрутом. Это не то же самое, что полученный ответ `401`, `429`, `500` или `529`. Сначала откройте актуальный [Claude Status](https://status.claude.com/), затем выполните команду из того же shell, где запускается Claude Code:

```bash
curl -I https://api.anthropic.com
```

Если curl тоже не подключается, проверяйте DNS, firewall, VPN, proxy и TLS этой сети. Если curl получает HTTP-ответ, а Claude Code продолжает падать, ищите различие в `/status`, переменных proxy/CA, WSL, macOS, Docker или в адресе `ANTHROPIC_BASE_URL`.

| Суффикс ошибки | Что он сужает | Первый шаг |
| --- | --- | --- |
| `ECONNREFUSED` | Целевой host или локальный proxy отказал в соединении | Проверить фактический endpoint и адрес proxy |
| `ECONNRESET` | Установленное соединение сбросил VPN, proxy, сетевое устройство или удаленная сторона | Сравнить один запуск в другой доверенной сети |
| `ETIMEDOUT` | Маршрут не завершил соединение вовремя | Проверить DNS, firewall, proxy и задержку маршрута |
| `fetch failed` | Сетевой слой не получил нормальный API-ответ | Прочитать следующую строку и выполнить тест из того же shell |
| Ошибка сертификата | TLS inspection или отсутствующий корпоративный CA | Подключить утвержденный CA bundle |
| HTTP status и JSON body | Запрос дошел до API или provider | Перейти к разбору возвращенного статуса |

Не меняйте одновременно ключ, DNS, VPN, модель, gateway и версию Claude Code. Случайный успех после шести изменений не показывает причину сбоя.

## Убедитесь, что это действительно ошибка соединения

![Матрица результатов curl и Claude Code](https://blog.laozhang.ai/posts/ru/claude-api-error-connection-error/img/route-matrix.webp)

Официальный [справочник ошибок Claude Code](https://code.claude.com/docs/ru/errors) относит `Unable to connect to API`, `ECONNREFUSED`, `ECONNRESET`, `ETIMEDOUT`, `fetch failed` и timeout с упоминанием сети или proxy к сетевой ветке. Практическая граница — наличие HTTP-ответа.

- Нет status code, response body и request ID: оставайтесь в ветке соединения.
- Пришел `401` или сообщение invalid key: сеть доставила запрос, нужна ветка authentication.
- Пришел `429`, `500` или `529`: API или настроенный provider ответил, поэтому нужен разбор конкретного статуса.
- Появилось `Connection closed mid-response`: вывод уже начался. Сохраните завершенные блоки и продолжите с последней целой части вместо повторного запуска всей работы.

Claude Code автоматически повторяет многие временные сетевые и серверные ошибки с увеличивающейся задержкой. Если итоговое сообщение уже видно в терминале, быстрые автоматические попытки не устранили проблему. Повторение той же команды без изменения маршрута обычно не дает новых данных.

## Проверьте маршрут из того же shell

Браузер, WSL, SSH, VS Code Remote и контейнер могут иметь разные DNS, proxy и хранилища сертификатов. Рабочий claude.ai в браузере не доказывает, что процесс `claude` видит `api.anthropic.com`.

Выполните проверку host и посмотрите только переменные маршрутизации:

```bash
curl -I https://api.anthropic.com
env | grep -Ei '^(ANTHROPIC_BASE_URL|ANTHROPIC_API_KEY|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|NODE_EXTRA_CA_CERTS)='
```

Не копируйте вывод, если там есть API key или пароль proxy. Важно лишь наличие переменной и выбранный ею host или путь к сертификату.

| Результат curl | Результат Claude Code | Вероятный владелец |
| --- | --- | --- |
| Host не разрешается | Ошибка | DNS или resolver WSL |
| Port 443 не открывается или timeout | Ошибка | Firewall, VPN, proxy или внешний маршрут |
| Ошибка certificate validation | Ошибка | TLS inspection и доверие к CA |
| Получен любой HTTP-ответ | Ошибка соединения | Среда процесса Claude Code, scope настроек или gateway |
| Получен ответ | 401/429/500/529 | Это уже не чистая connection error |

Успешный `curl -I` подтверждает базовую доступность host, но не проверяет учетную запись, модель, полный Messages request или совместимость gateway. Это диагностическая граница, а не финальный тест.

## Если curl тоже падает

Проверьте live status, но не делайте вывод, что зеленая страница гарантирует исправность каждого регионального или корпоративного маршрута. Затем измените один параметр:

1. Повторите тот же curl в другой доверенной сети — например, через мобильную точку доступа или домашнее соединение.
2. Если активен VPN, отключите его для одного теста. Если VPN обязателен по политике компании, передайте проверку allowlist сетевой команде, а не обходите контроль.
3. Убедитесь, что firewall разрешает фактический API host и адреса из официальных [требований сетевого доступа](https://code.claude.com/docs/ru/network-config#network-access-requirements).
4. В Linux или WSL проверьте `/etc/resolv.conf`: WSL может получить недоступный nameserver от host-системы.
5. Если DNS работает, но порт 443 дает timeout, исследуйте firewall, router, proxy и outbound route. Смена API key здесь не поможет.

`ECONNREFUSED` часто указывает на то, что конечный host или локальный proxy-порт отверг соединение. Проверьте, не отправляет ли `ANTHROPIC_BASE_URL` запрос на другой адрес. `ECONNRESET` означает, что соединение было установлено и затем сброшено; здесь важнее VPN, TLS-inspecting appliance, нестабильная сеть и политика длительных соединений.

## Настройте корпоративный proxy и доверенный CA

![Путь Claude Code через корпоративный proxy и доверенный CA](https://blog.laozhang.ai/posts/ru/claude-api-error-connection-error/img/proxy-ca-path.webp)

Claude Code считывает стандартные переменные proxy при запуске:

```bash
export HTTPS_PROXY=https://proxy.example.com:8080
export NO_PROXY=".example.internal"
claude
```

Используйте схему, host и порт, выданные вашей организацией. Claude Code не поддерживает SOCKS proxy. Если proxy выполняет TLS inspection, укажите утвержденный CA bundle:

```bash
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
claude
```

Не используйте `NODE_TLS_REJECT_UNAUTHORIZED=0`: эта переменная отключает проверку сертификатов. Не храните пароль proxy в репозитории или общем скрипте. Различия между shell, Desktop-managed, cloud и background session описаны в официальной [конфигурации корпоративной сети](https://code.claude.com/docs/ru/network-config).

Переменная, экспортированная после запуска Claude Code, не меняет уже работающий процесс. После правки proxy или CA перезапустите Claude Code. Для фоновых процессов и Desktop-managed sessions проверьте фактически загруженную конфигурацию через `/status` и debug log.

## Если curl работает, а Claude Code — нет

Запустите `/status` и проверьте активную credential, provider, proxy и endpoint. После этого разделите причины:

- **Неожиданный API key:** наличие `ANTHROPIC_API_KEY` может выбрать API-key route вместо ожидаемой подписки. Проверяйте только факт наличия, не печатайте секрет.
- **Неожиданный gateway:** `ANTHROPIC_BASE_URL` меняет пункт назначения. Официальный Anthropic API и сторонний relay — разные системы с разными владельцами и журналами.
- **WSL или remote IDE:** выполните один и тот же curl в host terminal, WSL и фактическом VS Code Remote shell. Сравните DNS, proxy и CA store.
- **macOS после удаления VPN:** клиент может оставить `utun` interface или network extension. Проверьте расширение в System Settings; не удаляйте неизвестные маршруты наугад.
- **Docker Desktop:** контейнерный runtime может перехватывать исходящий трафик. Если это безопасно для текущей работы, остановите его для одного контролируемого теста.
- **Background supervisor:** длительно живущий процесс мог унаследовать старую среду другого shell. Используйте поддерживаемый user или managed settings scope.

Если непонятно, какая credential или provider активны, сначала откройте [руководство по конфигурации Claude Code API](https://blog.laozhang.ai/ru/posts/claude-code-api-configuration), а затем меняйте значения.

## Подтвердите исправление маленьким запросом

После одного изменения перезапустите Claude Code и отправьте короткий запрос без чувствительных данных. Исправление подтверждено, когда одновременно выполняются три условия:

1. Тот же shell получает HTTP-ответ от официального host или утвержденного gateway.
2. `/status` показывает ожидаемые authentication и route.
3. Новый запрос завершается без прежней connection error.

Если вместо сетевой ошибки появился HTTP status, транспортный маршрут восстановлен. Перейдите к [Claude Code API Error 500](https://blog.laozhang.ai/ru/posts/claude-code-500-529-rate-limit), [Claude API 529 overloaded](https://blog.laozhang.ai/ru/posts/claude-api-error-529-overloaded) или [ошибке rate limit](https://blog.laozhang.ai/ru/posts/claude-rate-exceeded-error). После полученного ответа сервера не продолжайте переключать сеть без причины.

## Что передать в поддержку

Соберите время и часовой пояс, ОС, версию Claude Code, точный суффикс ошибки, тип маршрута, результат `curl -I`, наблюдение на status page и результат одного изменения сети или proxy. Указывайте host из `ANTHROPIC_BASE_URL` только если адрес не является внутренним.

Не отправляйте API keys, OAuth tokens, proxy passwords, private prompts, customer data и полный дамп environment. Для официального маршрута используйте Help Center или `/feedback`, если команда доступна; для корпоративного proxy или gateway отправьте тот же обезличенный пакет владельцу платформы.

Рабочее правило: если same-shell curl падает, исправляйте путь до host; если curl работает, а Claude Code нет, исправляйте фактическую среду процесса; если получен HTTP error, выходите из ветки соединения и обрабатывайте ответ.

## Источники

Внешние страницы, на которые ссылается это руководство, в порядке упоминания. Последнее обновление: 2026-08-04.

- [Claude Status](https://status.claude.com/) (status.claude.com)
- [справочник ошибок Claude Code](https://code.claude.com/docs/ru/errors) (code.claude.com)
- [требований сетевого доступа](https://code.claude.com/docs/ru/network-config) (code.claude.com)