Claude Code Unable to connect to API: ECONNRESET y ECONNREFUSED

Cuando Claude Code muestra API Error: Connection dropped (ECONNRESET), Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED), Can't reach the API server — check your internet or DNS (ENOTFOUND) o el antiguo Unable to connect to API (…), la petición no recibió ninguna respuesta HTTP: la conexión con la API falló o nunca llegó a completarse. No es un 401, 429, 500 ni 529, y cambiar la API key o el modelo no lo arregla. Además, cuando el error llega a la pantalla, Claude Code ya lo ha reintentado por defecto hasta 10 veces (los errores de certificado son la excepción), así que repetir la misma petición tampoco aporta nada.

Mira primero el estado de Claude y lanza esta prueba desde la misma shell en la que arrancas claude:

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

En Windows PowerShell escribe curl.exe -I https://api.anthropic.com, porque curl a secas es un alias de Invoke-WebRequest. Cualquier línea HTTP/… en la respuesta, incluso HTTP/2 404, significa que la red llega a la API. Si curl falla, el problema está en la red, el DNS, la VPN, el firewall o el proxy. Si curl responde y Claude Code no, el fallo suele estar en el entorno del proceso: un ANTHROPIC_BASE_URL olvidado, WSL, Docker, restos de una VPN o el gateway que usas. La excepción son algunas líneas de operador donde, según informes de usuarios, solo fallan los paquetes grandes y curl no lo nota.

Qué significa Connection dropped, Connection refused o ENOTFOUND

Desde la versión 2.1.227 Claude Code nombra el tipo de fallo y deja el código entre paréntesis. Antes, todos estos mensajes decían Unable to connect to API seguido del código, por eso los hilos y guías antiguos citan Unable to connect to API (ECONNRESET) o Unable to connect to API (ECONNREFUSED): es el mismo error con otro texto. Según la referencia de errores de Claude Code, un código que la herramienta no reconoce sigue apareciendo como Unable to connect to API (CÓDIGO).

Tres mensajes cercanos tienen otra lectura. Connection lost mid-response aparece cuando la respuesta ya había empezado a llegar: Claude Code conserva los bloques completos y basta con escribir continue. Socket is closed suele ser un proxy corporativo en Windows que corta un túnel ya abierto y se reintenta desde la versión 2.1.214, así que actualiza con claude update. API returned an empty or malformed response (HTTP 200) significa que respondió otra cosa en lugar de la API, típicamente el portal de inicio de sesión de una wifi de invitados, un proxy o un gateway.

Si en lugar de estos mensajes ves un código HTTP, la red funciona y el problema es otro: para 500 y 529 en Claude Code sigue Claude Code API Error 500 y 529: reanuda sin duplicar trabajo; para 429, Claude Rate Exceeded: qué límite has alcanzado y cómo resolverlo; para 403 o 503, Claude Code 403, 503 y 529: quién da el error y cómo arreglarlo; y si falla el inicio de sesión, Temporarily unable to authenticate en Claude: qué es y qué hacer.

¿Claude está fallando hoy? Cuándo es un incidente y cuándo es tu red

Abre status.claude.com. Si hay un incidente abierto en la API o en Claude Code, espera a que se resuelva: cambiar tu red en mitad de una caída solo añade ruido. Una página en verde no demuestra lo contrario, porque los fallos de una ruta concreta (un operador, una red corporativa, una VPN) no aparecen allí. Downdetector recoge quejas de usuarios; sirve para ver si hay más gente afectada, no para saber la causa.

La documentación oficial describe cómo trata Claude Code los cortes pasajeros: reintenta hasta 10 veces con espera exponencial (CLAUDE_CODE_MAX_RETRIES, máximo 15). Mientras tanto ves Retrying in Ns · attempt x/y y, si no llegan datos en 20 segundos, Waiting for API response · will retry in … · check your network. Si ese aviso vuelve en cada intento, trátalo como un problema de red, no como una caída puntual. Para ver el primer fallo sin esperar todos los reintentos mientras diagnosticas:

CLAUDE_CODE_MAX_RETRIES=0 claude -p "hola"

La prueba que decide la rama: curl -I desde la misma shell

El navegador, WSL, una sesión SSH, VS Code Remote y un contenedor pueden tener DNS, proxy y certificados distintos. Que claude.ai abra en el navegador no prueba que el proceso claude llegue a api.anthropic.com. Por eso la prueba se hace en la shell exacta desde la que lanzas Claude Code, junto con una lista de las variables que cambian el destino:

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

En PowerShell, la segunda línea equivale a Get-ChildItem Env: | Where-Object Name -Match 'ANTHROPIC_BASE_URL|PROXY|NODE_EXTRA_CA_CERTS'. Si alguna variable lleva contraseñas de proxy, no pegues la salida en ningún foro; solo necesitas saber si existe y a qué host apunta.

La imagen usa el texto antiguo Unable to connect to API y marca la última fila como fallo de conexión; vale la tabla de abajo: si curl recibe 401, 429, 500 o 529, ya no es un error de conexión.

curl -I solo comprueba que el transporte funciona. No valida la cuenta, el modelo ni la compatibilidad de un gateway, pero basta para saber en qué rama estás.

Mismo mensaje, causas distintas: prueba con Claude Code 2.1.306

El texto del error ayuda, pero no siempre señala al culpable. Las tres condiciones siguientes se ejecutaron el 21 de octubre de 2026 en un solo Mac con Claude Code 2.1.306, claude -p en un entorno limpio (env -i), una clave ficticia y CLAUDE_CODE_MAX_RETRIES=0, sin coste ni credenciales reales:

Desde la misma shell, curl -sI https://api.anthropic.com devolvió HTTP/1.1 200 Connection established (el proxy local) y después HTTP/2 404: el transporte funcionaba.

De ahí salen tres conclusiones prácticas:

• Gateway caído y proxy caído dan el mismo texto. Con Connection refused, revisa a la vez ANTHROPIC_BASE_URL y HTTPS_PROXY; el mensaje no distingue entre ambos.
• Una VPN en modo TUN puede disfrazar un fallo de DNS. Algunas VPN y proxies en modo TUN usan lo que se llama DNS fake-IP: responden a cada consulta con una dirección falsa del rango 198.18.x.x. El nombre parece resolverse, la VPN no consigue llegar al destino real y corta la conexión, así que lo que era un ENOTFOUND llega como Connection dropped (ECONNRESET). En la prueba, el dominio inexistente se resolvió a 198.18.13.146 y api.anthropic.com a 198.18.1.5. Compruébalo en macOS con dscacheutil -q host -a name api.anthropic.com, o en Linux con getent hosts api.anthropic.com.
• Un 404 de curl cuenta como «llegó». No hace falta un 200 para descartar la red.

Queda fuera de esta prueba: Windows, un ENOTFOUND real sin DNS fake-IP y el problema de MTU descrito más abajo.

Si curl también falla: DNS, VPN, firewall o WSL

Cambia una sola condición cada vez y repite el mismo curl. Si cambias DNS, VPN, red y clave a la vez y vuelve a funcionar, no sabrás qué lo arregló ni podrás evitar que se repita.

1. Otra red. Comparte datos desde el móvil y repite curl y Claude Code. Si en el hotspot funciona, el problema está en tu red, tu router o la ruta de tu operador.
2. La VPN, en el estado contrario. La ayuda de Claude sobre errores de conexión de API recomienda no usar VPN, y a otros usuarios una VPN les resuelve el problema (lo verás en la sección siguiente). Las dos cosas son ciertas en redes distintas: trata la VPN como una variable más, cámbiala una vez y observa. Si tu empresa exige VPN, pide a tu equipo de red que revise la lista de permitidos en vez de saltártela.
3. El firewall. Debe permitir los hosts de los requisitos de acceso a la red de Claude Code.
4. DNS en Linux y WSL. Revisa que /etc/resolv.conf no apunte a un servidor de nombres inaccesible. WSL puede heredar del host un resolver roto mientras el navegador de Windows funciona con normalidad.

Si DNS resuelve pero la conexión al puerto 443 agota el tiempo, el problema está en el firewall, el router, el proxy o la ruta de salida. Ninguna clave nueva cambia eso.

Connection dropped (ECONNRESET) con Movistar: informes de MTU

Hay un caso que no encaja en la tabla anterior: curl, el navegador y claude.ai funcionan, pero Claude Code falla con Connection dropped (ECONNRESET) durante minutos u horas en la conexión directa de casa o de la oficina, y el error desaparece con una VPN o con el hotspot del móvil.

Lo documentan usuarios en el issue #94225 del repositorio de Claude Code en GitHub, abierto el 14 de septiembre de 2026 por un cliente de Movistar en España, con comentarios desde Alemania, Hungría, Vietnam, Polonia (Netia) y de nuevo España (Movistar, 9 de octubre de 2026). Un caso anterior de Argentina, el #74767, se cerró automáticamente por inactividad. Las mediciones de MTU se enviaron también como issue #100706 de Claude Code. A 21 de octubre de 2026 ambos siguen abiertos y sin respuesta del equipo de Anthropic.

Lo que miden esos usuarios, no Anthropic:

• La primera hipótesis apuntaba al intercambio de claves poscuántico de TLS 1.3 (X25519MLKEM768), que produce un primer mensaje TLS grande.
• Mediciones posteriores desde Polonia y España apuntan al tamaño de paquete (MTU de la ruta): con la MTU de la interfaz en 1500 solo salían bien entre 0 de 10 y 8 de 52 conexiones; con 1492, 1480, 1460, 1440 o 1400, todas (10 de 10, y 40 de 40 en otra serie a 1400).
• El mismo usuario español avisa de que otro Mac en su misma red funciona con MTU 1500, así que no descarta un factor del propio equipo.

Si estás exactamente en ese caso (curl funciona, el hotspot o la VPN lo arreglan, macOS), la prueba que usaron es temporal y reversible:

networksetup -getMTU Wi-Fi           # anota el valor actual
sudo networksetup -setMTU Wi-Fi 1400 # prueba
sudo networksetup -setMTU Wi-Fi 1500 # vuelve al valor que anotaste

Wi-Fi es el nombre del servicio de red; si usas cable, networksetup -listallhardwareports muestra el nombre correcto. Esta prueba no se ha reproducido en el Mac de la sección anterior, y los informes solo documentan macOS. Si confirma el patrón, deja tus datos (operador, país, versión, resultados por MTU) en el issue #94225 en lugar de abrir otro: así Anthropic ve el alcance real del problema.

Curl funciona y Claude Code falla: ANTHROPIC_BASE_URL, WSL, Docker

Cuando la red responde y Claude Code no, la causa suele estar entre el proceso y la red. Ejecuta /status dentro de Claude Code para ver qué credencial, proveedor, proxy y endpoint usa, y revisa por este orden:

Un ANTHROPIC_BASE_URL olvidado. Si está definido, Claude Code envía las peticiones a esa dirección y no a api.anthropic.com. Un valor que apunta a un proxy o gateway local que ya no está en marcha da Connection refused aunque curl llegue a la API, como se vio en la prueba. Búscalo en la shell y en el bloque env de los archivos de configuración:

echo "$ANTHROPIC_BASE_URL"
grep -n "ANTHROPIC_BASE_URL\|HTTPS_PROXY" ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

En PowerShell: echo $env:ANTHROPIC_BASE_URL. Bórralo del perfil de la shell o de los settings y abre una terminal nueva: una variable eliminada sigue viva en la sesión que ya estaba abierta.

Un gateway que rechaza la búsqueda de herramientas. Si ANTHROPIC_BASE_URL apunta a tu gateway a propósito y todas las peticiones, sin excepción, terminan en Connection dropped, prueba ENABLE_TOOL_SEARCH=false claude. Desde la versión 2.1.304 Claude Code activa por defecto la búsqueda de herramientas también detrás de un gateway, y algunos rechazan esos campos. Este ajuste no aplica si te conectas directamente a la API de Anthropic. Para revisar qué gateway y credencial están activos, consulta la configuración de Claude Code API: claves, settings.json, modelos y gateways.

WSL o IDE remoto. Ejecuta el mismo curl en la terminal del host, dentro de WSL y en la terminal integrada de VS Code Remote. Cada una puede tener su propio DNS, proxy y almacén de certificados. Si el problema es la extensión de VS Code y no la conexión, sigue Claude Code no funciona en VS Code: primero identifica la superficie que falla.

Docker Desktop. Docker Desktop y otros entornos de contenedores pueden interceptar el tráfico saliente. Ciérralos durante una prueba para descartarlos.

Restos de una VPN en macOS. Un cliente VPN desconectado o desinstalado puede dejar interfaces de túnel o reglas de enrutamiento, y la documentación de Claude Code lo incluye entre las causas cuando curl sí funciona. Busca interfaces utun sobrantes con ifconfig y elimina la extensión de red de esa VPN en Ajustes del Sistema; no borres rutas que no reconozcas.

Proxy corporativo y certificados: HTTPS_PROXY y NODE_EXTRA_CA_CERTS

La imagen sugiere probar una URL /status y esperar un 200; la prueba correcta es la de esta sección, curl -I https://api.anthropic.com a través del proxy, y cualquier respuesta HTTP sirve.

Claude Code lee las variables de proxy estándar (HTTPS_PROXY, HTTP_PROXY, NO_PROXY) al arrancar, así que deben estar definidas antes de lanzar claude:

export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,127.0.0.1,.example.internal"
export NODE_EXTRA_CA_CERTS=/ruta/a/ca-corporativa.pem
claude

Usa el esquema, host y puerto que te dé tu organización. Los proxies SOCKS no están soportados. Antes de culpar a Claude Code, prueba el mismo proxy con curl: curl -x http://proxy.example.com:8080 -I https://api.anthropic.com. Si falla igual, el problema es la configuración del proxy.

• Couldn't connect through your proxy (ERR_PROXY_TUNNEL): el proxy rechazó el túnel. Revisa las credenciales y pide que permita el host de la API.
• Connection refused con HTTPS_PROXY definido: puede que el proxy no esté escuchando en ese puerto; en la prueba anterior, un proxy apagado dio exactamente este mensaje.
• Errores de certificado (UNABLE_TO_GET_ISSUER_CERT_LOCALLY, SELF_SIGNED_CERT_IN_CHAIN): un proxy con inspección TLS firma el tráfico con su propia CA. Exporta el bundle aprobado y apúntalo con NODE_EXTRA_CA_CERTS. Desde la versión 2.1.199 estos errores no se reintentan, por eso aparecen al primer intento. Durante /login el mensaje cambia a SSL certificate error (…) Run claude doctor for details.

No uses NODE_TLS_REJECT_UNAUTHORIZED=0: desactiva por completo la validación de certificados. Tampoco guardes contraseñas de proxy en scripts del repositorio. Las variables exportadas después de arrancar Claude Code no afectan al proceso en marcha; reinícialo tras cada cambio. La configuración de red de Claude Code explica el resto de opciones de proxy y CA.

Unable to connect to Anthropic services en el primer inicio

En la primera ejecución, antes del inicio de sesión, Claude Code comprueba que llega a api.anthropic.com y a platform.claude.com, con 10 segundos por sonda y la misma configuración de proxy que las peticiones normales. Si falla, imprime el motivo y sale, con líneas como Failed to connect to api.anthropic.com: ECONNREFUSED, Connection to api.anthropic.com timed out after 10 seconds o A proxy is configured via HTTPS_PROXY. Check that it allows connections to the host above.

Las comprobaciones son las mismas de las secciones anteriores: curl desde la misma shell, firewall y proxy. Si el mensaje nombra una variable de proxy, revisa que apunte al proxy correcto y que este permita HTTPS hacia el host citado. Si tu red está abierta y el fallo persiste, consulta la lista de países donde Anthropic ofrece servicio: puede que Claude Code no esté disponible en el tuyo.

anthropic.APIConnectionError: Connection error. en tu código

En el SDK de Python, APIConnectionError significa que no hubo respuesta HTTP del servidor. El mensaje es siempre el mismo y corto, Connection error.; la causa real está en e.__cause__. Este script lo imprime y, de paso, sirve como prueba de transporte: si la red funciona, recibirás una respuesta HTTP (con una clave válida, un mensaje; con una clave errónea, un 401), y en ambos casos la conexión ya no es el problema.

import anthropic

# Necesita ANTHROPIC_API_KEY definida; para probar la red vale una clave errónea
client = anthropic.Anthropic(max_retries=0)  # ver el primer fallo sin reintentos

try:
    client.messages.create(
        model="claude-opus-5-5",
        max_tokens=16,
        messages=[{"role": "user", "content": "ping"}],
    )
    print("Conexión y petición correctas")
except anthropic.APIConnectionError as e:
    print("Sin respuesta HTTP:", type(e).__name__, repr(e.__cause__))
    print("base_url en uso:", client.base_url)
except anthropic.APIStatusError as e:
    print("La API respondió con HTTP", e.status_code)

Con el SDK 1.17.0 de Python, el 21 de octubre de 2026, dos casos dieron el mismo mensaje con causas muy distintas:

Qué más conviene saber del SDK:

• Reintentos y tiempos. Reintenta 2 veces por defecto (max_retries). En la versión 1.17.0 el cliente traía 5 segundos para conectar y 600 para leer. APITimeoutError es una subclase de APIConnectionError, así que el except anterior también captura los timeouts; type(e).__name__ los distingue.
• Destino. ANTHROPIC_BASE_URL también lo lee el SDK; si está definido y apunta a un servicio apagado, verás Connection refused en __cause__, igual que en Claude Code.
• Proxy. Pásalo de forma explícita, como indica la documentación del SDK de Python de Anthropic: anthropic.Anthropic(http_client=anthropic.DefaultHttpxClient(proxy="http://proxy.example.com:8080")). La forma en que el cliente HTTP del SDK trata las variables HTTPS_PROXY no figura en esa documentación, así que no cuentes con ellas.
• TypeScript. La clase equivalente también es APIConnectionError, con 2 reintentos por defecto (maxRetries), 10 minutos de timeout y APIConnectionTimeoutError cuando se agota.
• Peticiones largas. La página de errores de la Claude API advierte que algunas redes cortan conexiones inactivas: para respuestas largas usa streaming o Message Batches en lugar de una petición que espere muchos minutos sin datos.

Si en el mismo proyecto también usas OpenAI y el error viene de ese SDK, la lógica es parecida pero las clases cambian: Error de conexión de OpenAI API: corrige APIConnectionError probando la ruta.

Cómo confirmar que está arreglado y cuándo escalar

Tras un único cambio, abre una terminal nueva, arranca Claude Code y envía una petición breve sin datos sensibles. Puedes darlo por resuelto cuando se cumplen las tres cosas:

1. Desde esa shell, curl recibe una respuesta HTTP de api.anthropic.com o del gateway aprobado.
2. /status muestra la credencial y el endpoint que esperabas.
3. Una petición nueva termina sin el error de conexión, y sigue así un rato (en el caso del MTU los fallos iban por rachas).

Si el error se convierte en un código HTTP, la conexión ya funciona: cambia a la guía de ese código. Para 529 o 500 en tu propio código, Error 529 en Claude API: configura reintentos y controla la sobrecarga y Error 500 en Claude API: cómo reintentar y qué hacer si persiste.

Deja de cambiar cosas y escala cuando:

• Hay un incidente en status.claude.com: espera; tu configuración no tiene nada que corregir.
• La red es de tu empresa: entrega a tu equipo de red el resultado de curl, el mensaje exacto y los hosts de los requisitos de acceso.
• Tu caso coincide con el de los operadores: suma tus datos al issue #94225; no hay arreglo oficial.
• Nada de lo anterior encaja: abre un caso desde el icono de chat del Centro de ayuda de Claude o, en la Console, con tus iniciales → Obtener ayuda; desde Claude Code, /bug envía un informe.

Incluye fecha, hora y zona horaria, sistema operativo, claude --version, el mensaje completo, el resultado de curl -I, si hay ANTHROPIC_BASE_URL o proxy definidos (sin valores secretos) y qué cambio probaste. No envíes API keys, tokens OAuth, contraseñas de proxy, prompts privados ni un volcado completo del entorno.

Preguntas frecuentes sobre los errores de conexión de Claude

¿Qué significa «error de API» en Claude?

Es la etiqueta que Claude Code pone delante de los fallos al hablar con la API (API Error: …). Lo que importa es lo que viene detrás: si es un código HTTP (401, 429, 500, 529), la API respondió y el problema es de cuenta, límite o servidor; si es Connection dropped, Connection refused, Can't reach the API server o Request timed out, no hubo respuesta y el problema está en el camino entre tu equipo y la API.

¿Connection lost mid-response es lo mismo que Connection dropped?

No. Connection dropped (ECONNRESET) corta la conexión antes de recibir nada; Connection lost mid-response aparece cuando la respuesta ya estaba llegando. En ese segundo caso Claude Code conserva lo que llegó completo y puedes escribir continue. Antes de la versión 2.1.227 se llamaba Connection closed mid-response.

¿Sirve de algo reinstalar Claude Code o cambiar la API key?

Cambiar la key no, porque el error ocurre antes de que la API llegue a leerla. Reinstalar tampoco suele ayudar, pero actualizar con claude update sí puede: versiones recientes reintentan Socket is closed y muestran mensajes más claros. Si actualizas, hazlo como un cambio aislado y vuelve a probar.