Claude Code Unable to connect to API: solución para ECONNREFUSED, ECONNRESET y proxy

Unable to connect to API significa que Claude Code no completó la conexión TCP con la ruta API activa. No es lo mismo que recibir un 401, 429, 500 o 529. Revisa primero el estado de Claude en vivo y ejecuta esto desde la misma shell que inicia Claude Code:

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

Si curl tampoco conecta, revisa DNS, firewall, VPN, proxy o TLS en esa red. Si curl recibe una respuesta HTTP pero Claude Code sigue fallando, revisa /status, las variables de proxy y CA, WSL o macOS, Docker y el host seleccionado por ANTHROPIC_BASE_URL.

No reinstales Claude Code, rotes la clave, cambies DNS, VPN, modelo y gateway a la vez. Aunque vuelva a funcionar, habrás perdido la señal que identifica la causa.

Confirma que sigue siendo un fallo de conexión

La referencia oficial de errores de Claude Code agrupa Unable to connect to API, ECONNREFUSED, ECONNRESET, ETIMEDOUT, fetch failed y los timeouts que mencionan red o proxy dentro de los errores de red. La frontera útil es si existe una respuesta HTTP.

• Sin status code, response body ni request ID: continúa en la rama de conexión.
• Con 401 o invalid key: la red alcanzó una capa API; revisa autenticación.
• Con 429, 500 o 529: la API o el provider configurado respondió; trata ese status.
• Con Connection closed mid-response: el streaming ya había empezado. Conserva los bloques completos y continúa desde el último punto válido.

Claude Code reintenta automáticamente muchos fallos transitorios de conexión y servidor con espera exponencial. Cuando el error final aparece en el terminal, los reintentos rápidos no lo eliminaron. Repetir lo mismo sin cambiar la ruta no aporta un dato nuevo.

Toma una línea base desde la misma shell

El navegador, WSL, SSH, VS Code Remote y un container pueden tener DNS, proxy y almacenes de certificados distintos. Poder abrir claude.ai en el navegador no prueba que el proceso claude llegue a api.anthropic.com.

Comprueba el host y solo las variables relacionadas con la ruta:

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)='

No pegues el resultado si muestra una API key o contraseña de proxy. Solo necesitas saber si la variable existe y qué host, proxy o archivo de certificado selecciona.

Un curl -I exitoso prueba reachability básica del host. No valida la cuenta, un Messages request completo, el modelo ni la compatibilidad del gateway. Es una prueba de rama, no una validación end-to-end.

Si curl también falla, corrige la ruta de red

Consulta el status actual, pero una página verde no garantiza que todas las rutas regionales, ISP o redes corporativas estén sanas. Después cambia una sola condición:

1. Ejecuta el mismo curl una vez en otra red fiable, como un hotspot móvil o la conexión doméstica.
2. Si hay una VPN activa, desconéctala para una comparación. Si la política de la empresa exige VPN, pide al equipo de red revisar allowlist en vez de eludir el control.
3. Confirma que el firewall permite el host API efectivo y los destinos de los requisitos de acceso de red.
4. En Linux o WSL, revisa que /etc/resolv.conf no apunte a un nameserver inaccesible. El navegador de Windows puede funcionar mientras falla el resolver de WSL.
5. Si DNS resuelve pero el puerto 443 agota el tiempo, investiga firewall, router, proxy y ruta de salida. Cambiar la clave no corrige ese camino.

ECONNREFUSED suele indicar que el host efectivo o el puerto del proxy local rechazó la conexión. Comprueba si ANTHROPIC_BASE_URL está enviando el tráfico a otro destino. ECONNRESET indica que hubo conexión y después se reinició; aquí importan más VPN, inspección TLS, calidad de red y política de conexiones largas.

Configura el proxy corporativo y la CA como una sola ruta

Claude Code lee las variables proxy estándar al iniciarse:

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

Usa el scheme, host y puerto entregados por tu organización. Claude Code no admite proxies SOCKS. Si el proxy hace inspección TLS, configura el bundle CA aprobado:

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

No uses NODE_TLS_REJECT_UNAUTHORIZED=0: desactiva la validación de certificados. Tampoco guardes contraseñas del proxy en scripts del repositorio. La configuración de red empresarial explica proxy, CA store y diferencias de scope entre shell, Desktop, cloud y procesos en segundo plano.

Una variable exportada después de iniciar Claude Code no cambia el proceso activo. Reinicia Claude Code tras modificar proxy o CA. En una sesión gestionada por Desktop o un background supervisor, la shell actual puede no ser el scope efectivo; compruébalo con /status y debug log.

Si curl funciona y solo falla Claude Code

Ejecuta /status dentro de Claude Code y verifica credential, provider, proxy y endpoint activos. Después separa estas causas:

• API key inesperada: ANTHROPIC_API_KEY puede seleccionar la ruta de API key cuando esperabas usar una suscripción. Confirma solo si existe; no imprimas el secreto.
• Gateway inesperado: ANTHROPIC_BASE_URL cambia el destino. La API oficial y un relay de terceros son sistemas distintos con responsables distintos.
• WSL o IDE remoto: ejecuta el mismo curl en el terminal host, WSL y la shell real de VS Code Remote. Compara DNS, proxy y CA store.
• Ruta VPN antigua en macOS: un cliente desconectado o eliminado puede dejar una interfaz utun o extensión de red. Revisa System Settings y no borres rutas que no entiendas.
• Docker Desktop: el runtime puede interceptar tráfico saliente. Si es seguro para tu trabajo, ciérralo durante una sola prueba controlada.
• Proceso en segundo plano: un supervisor persistente puede haber heredado el entorno de otra shell. Coloca las variables necesarias en el user o managed settings scope compatible.

Si no sabes qué ruta de autenticación o provider está activa, usa primero la guía de configuración de Claude Code API.

Verifica la reparación con una petición pequeña

Después de un solo cambio, reinicia Claude Code y envía una petición breve sin datos sensibles. La reparación queda confirmada cuando se cumplen las tres condiciones:

1. La misma shell recibe una respuesta HTTP del host oficial o gateway aprobado.
2. /status muestra la autenticación y ruta previstas.
3. Una petición nueva termina sin el mismo error de conexión.

Si el error cambia a un estado HTTP, la ruta de transporte ya llegó a una capa API. Sigue la guía de Claude Code API Error 500, Claude API 529 overloaded o rate limit de Claude API. Cuando el servidor ya respondió, no sigas alternando la red sin motivo.

Escala con un paquete pequeño y redactado

Anota fecha, hora y zona horaria, sistema operativo, versión de Claude Code, sufijo exacto, tipo de ruta, resultado de curl -I, observación del status y resultado de cambiar una sola condición de red o proxy. Comparte el host de ANTHROPIC_BASE_URL solo si no es una dirección privada.

No envíes API keys, OAuth tokens, contraseñas de proxy, prompts privados, datos de clientes ni un volcado completo del entorno. Para la ruta oficial usa Help Center o /feedback cuando esté disponible; para una red corporativa o gateway, entrega el mismo paquete redactado a su owner.

La regla final es directa: si curl falla en la misma shell, repara el camino al host; si curl funciona y Claude Code falla, repara el entorno efectivo del proceso; si vuelve un error HTTP, abandona la rama de conexión y procesa esa respuesta.