Claude Code Unable to connect to API: qué significa y 5 soluciones fáciles (probadas)

Respuesta corta: Claude Code Unable to connect to API significa que la conexión entre Claude Code y la API no llegó a establecerse. Casi nunca es que se haya caído internet. Lo habitual es que algo en tu equipo mande la petición a otro sitio: un ANTHROPIC_BASE_URL que quedó de una prueba, una variable de proxy que apunta a un programa ya cerrado, una VPN o un DNS roto. Lo primero es ejecutar curl -I https://api.anthropic.com en la misma terminal. Si curl devuelve cualquier código HTTP y Claude Code sigue fallando, revisa ANTHROPIC_BASE_URL y las variables de proxy. Reprodujimos el error en un equipo de pruebas con Claude Code 2.1.312 y abajo está la salida real. Los mensajes y las soluciones siguen la referencia oficial de errores de Claude Code, revisada el 29 de octubre de 2026.

Cómo aparece Claude Code Unable to connect to API

Desde la versión 2.1.227 el mensaje dice qué tipo de fallo fue y deja el código entre paréntesis. Estas son las variantes que recoge la documentación oficial:

Unable to connect to API. Check your internet connection
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
No internet route — check your connection or VPN (EHOSTUNREACH)
Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host
Connection dropped (ECONNRESET)
Request timed out. Check your internet connection and proxy settings

En versiones anteriores a la 2.1.227 verás el formato antiguo, por ejemplo Unable to connect to API (ECONNREFUSED), que es el que aparece en muchos foros. Según la documentación, Claude Code reintenta solo hasta 10 veces antes de mostrar el error, así que cuando lo ves ya agotó los reintentos.

Nuestra prueba: una base URL o un proxy muerto da Connection refused

Usamos un equipo Linux con Claude Code 2.1.312 y una clave de API falsa. Pusimos CLAUDE_CODE_MAX_RETRIES=0 para que el error saliera al momento y no después de los reintentos.

• curl -sI https://api.anthropic.com devolvió HTTP/2 404. Ese 404 es buena señal: el servidor respondió, así que la red funciona.
• Con ANTHROPIC_BASE_URL=http://127.0.0.1:9 (un puerto donde no escucha nada), claude -p hi mostró API Error: Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED).
• Con HTTPS_PROXY=http://127.0.0.1:9 en su lugar, salió exactamente el mismo Connection refused.
• Tras unset ANTHROPIC_BASE_URL HTTPS_PROXY, el mismo comando respondió Invalid API key · Fix external API key. La clave era falsa a propósito; lo que importa es que la petición volvió a llegar a la API.

Es decir, el caso más típico de Claude Code Unable to connect to API es el de curl funciona y Claude Code no, porque Claude Code lee ajustes que curl ignora. Un detalle más: con ANTHROPIC_BASE_URL=https://api.anthropic.invalid (un dominio que no existe) nuestro equipo dio Connection dropped (ECONNRESET) en vez de ENOTFOUND, porque sale a internet a través de un proxy. En una conexión doméstica normal lo esperable es la variante ENOTFOUND. El código entre paréntesis depende de lo que haya entre tú y la API.

Cómo arreglar Claude Code Unable to connect to API, paso a paso

Abre la terminal donde falla claude y ejecuta:

curl -I https://api.anthropic.com
echo $ANTHROPIC_BASE_URL
env | grep -i proxy

• curl tampoco conecta. El problema es la red: Wi-Fi, cortafuegos, VPN o el proxy de la empresa. En PowerShell usa curl.exe -I https://api.anthropic.com, porque curl a secas llama a Invoke-WebRequest. Si en la oficina hay proxy, define HTTPS_PROXY antes de abrir Claude Code (ver configuración de red).
• curl conecta y ANTHROPIC_BASE_URL tiene valor. Claude Code está enviando las peticiones a esa dirección. Si ya no la usas, bórrala del perfil de la shell y revisa el bloque env de ~/.claude/settings.json y de .claude/settings.local.json en el proyecto (te explicamos dónde está settings.json). Luego abre una terminal nueva.
• La variable de proxy apunta a un programa cerrado. Ejecuta unset HTTPS_PROXY HTTP_PROXY y vuelve a probar.
• WSL o Linux. Revisa el nameserver de /etc/resolv.conf. WSL puede heredar de Windows un DNS que no responde.
• macOS después de quitar una VPN. Busca interfaces utun sobrantes con ifconfig y elimina la extensión de red de la VPN en Ajustes del Sistema.
• Docker Desktop. Ciérralo y prueba otra vez para descartar que intercepte el tráfico.
• Usas un gateway y todo termina en Connection dropped. Prueba con ENABLE_TOOL_SEARCH=false. La documentación indica que algunos gateways rechazan los campos de tool search que Claude Code envía por defecto.

Casos reales en GitHub

• En el issue #74120 de anthropics/claude-code, el usuario pensó al principio que la culpa era de una actualización de macOS. Al final era un .claude/settings.local.json del proyecto con ANTHROPIC_BASE_URL apuntando a http://127.0.0.1:8787, donde no corría nada. Solo fallaban las sesiones abiertas en ese repositorio y se arregló quitando el bloque env.
• En el issue #84211, un usuario de Windows vio que la 2.1.220 funcionaba y la 2.1.221 y 2.1.222 daban ECONNRESET. Según su propio diagnóstico, la causa era un Winsock LSP que había dejado un acelerador de red desinstalado. Anthropic no lo confirmó en ese hilo.

¿Puede ser por el país?

Si estás en España o en Latinoamérica, es poco probable. La lista oficial de países admitidos incluye España, México, Argentina, Colombia, Chile y Perú, entre otros. La documentación menciona el país solo para el mensaje Unable to connect to Anthropic services, que sale en la configuración inicial cuando Claude Code comprueba api.anthropic.com y platform.claude.com. Si tu red está abierta y aun así falla, comprueba que tu país esté en esa lista.

Errores parecidos que no son este

• 529 Overloaded. La conexión funcionó y el servidor está saturado. Lo explicamos en Claude Code error 529.
• 429. La conexión funcionó y llegaste a un límite. Mira el error 429 en Claude Code.
• Para el resto de mensajes, tienes la guía de errores de Claude Code.

Preguntas frecuentes

¿Por qué curl funciona y Claude Code dice Unable to connect to API?

Porque Claude Code lee ANTHROPIC_BASE_URL, las variables de proxy y el bloque env de sus archivos de ajustes, y curl no. En nuestra prueba, una base URL muerta dio Connection refused mientras curl llegaba a la API sin problema.

¿Claude Code reintenta antes de mostrar el error?

Sí. La documentación oficial habla de hasta 10 reintentos con espera creciente. Puedes bajar ese número con CLAUDE_CODE_MAX_RETRIES.

¿Es un problema que curl -I https://api.anthropic.com devuelva 404?

No. Con la red funcionando nosotros obtuvimos HTTP/2 404. Cualquier código HTTP significa que el servidor contestó.

¿Tengo que reinstalar Claude Code?

Normalmente no, porque reinstalar no borra las variables de entorno ni los archivos de ajustes. Si quieres empezar de cero, sigue nuestra guía para instalar Claude Code.