Сообщение Unable to connect to API означает, что Claude Code не завершил TCP-соединение с текущим API-маршрутом. Это не то же самое, что полученный ответ 401, 429, 500 или 529. Сначала откройте актуальный Claude Status, затем выполните команду из того же shell, где запускается Claude Code:
bashcurl -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. Случайный успех после шести изменений не показывает причину сбоя.
Убедитесь, что это действительно ошибка соединения
Официальный справочник ошибок Claude Code относит 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 и посмотрите только переменные маршрутизации:
bashcurl -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, но не делайте вывод, что зеленая страница гарантирует исправность каждого регионального или корпоративного маршрута. Затем измените один параметр:
- Повторите тот же curl в другой доверенной сети — например, через мобильную точку доступа или домашнее соединение.
- Если активен VPN, отключите его для одного теста. Если VPN обязателен по политике компании, передайте проверку allowlist сетевой команде, а не обходите контроль.
- Убедитесь, что firewall разрешает фактический API host и адреса из официальных требований сетевого доступа.
- В Linux или WSL проверьте
/etc/resolv.conf: WSL может получить недоступный nameserver от host-системы. - Если 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 при запуске:
bashexport HTTPS_PROXY=https://proxy.example.com:8080 export NO_PROXY=".example.internal" claude
Используйте схему, host и порт, выданные вашей организацией. Claude Code не поддерживает SOCKS proxy. Если proxy выполняет TLS inspection, укажите утвержденный CA bundle:
bashexport NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem claude
Не используйте NODE_TLS_REJECT_UNAUTHORIZED=0: эта переменная отключает проверку сертификатов. Не храните пароль proxy в репозитории или общем скрипте. Различия между shell, Desktop-managed, cloud и background session описаны в официальной конфигурации корпоративной сети.
Переменная, экспортированная после запуска 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: клиент может оставить
utuninterface или network extension. Проверьте расширение в System Settings; не удаляйте неизвестные маршруты наугад. - Docker Desktop: контейнерный runtime может перехватывать исходящий трафик. Если это безопасно для текущей работы, остановите его для одного контролируемого теста.
- Background supervisor: длительно живущий процесс мог унаследовать старую среду другого shell. Используйте поддерживаемый user или managed settings scope.
Если непонятно, какая credential или provider активны, сначала откройте руководство по конфигурации Claude Code API, а затем меняйте значения.
Подтвердите исправление маленьким запросом
После одного изменения перезапустите Claude Code и отправьте короткий запрос без чувствительных данных. Исправление подтверждено, когда одновременно выполняются три условия:
- Тот же shell получает HTTP-ответ от официального host или утвержденного gateway.
/statusпоказывает ожидаемые authentication и route.- Новый запрос завершается без прежней connection error.
Если вместо сетевой ошибки появился HTTP status, транспортный маршрут восстановлен. Перейдите к Claude Code API Error 500, Claude API 529 overloaded или ошибке rate limit. После полученного ответа сервера не продолжайте переключать сеть без причины.
Что передать в поддержку
Соберите время и часовой пояс, ОС, версию 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, выходите из ветки соединения и обрабатывайте ответ.
