# Claude Code Unable to connect to API: ECONNRESET y ECONNREFUSED

> Connection dropped (ECONNRESET) o Connection refused en Claude Code: no hubo respuesta HTTP; curl en la misma shell dice si falla la red o tu entorno.

- URL: https://blog.laozhang.ai/es/posts/claude-api-error-connection-error
- Published: 2026-08-04
- Updated: 2026-10-21
- Author: LaoZhang AI Team (https://blog.laozhang.ai/es/about)
- Topic: Claude Code
- Tags: Claude Code, Unable to connect to API, ECONNRESET, ECONNREFUSED, Proxy, Solución de problemas

---
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](https://status.claude.com/) y lanza esta prueba desde la misma shell en la que arrancas `claude`:

```bash
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](https://code.claude.com/docs/es/errors), un código que la herramienta no reconoce sigue apareciendo como `Unable to connect to API (CÓDIGO)`.

| Mensaje actual (tras `API Error: `) | Texto antiguo | Qué te dice | Primera comprobación |
| --- | --- | --- | --- |
| `Connection dropped (ECONNRESET)` | `Unable to connect to API (ECONNRESET)` | La conexión llegó a abrirse y alguien la cortó: VPN, proxy, inspección TLS, gateway o la ruta de tu operador | Repetir la prueba con otra red (hotspot del móvil) o con la VPN en el estado contrario |
| `Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)` o `(ConnectionRefused)` | `Unable to connect to API (ECONNREFUSED)` | Nadie acepta la conexión en el host y puerto que usa el proceso | `ANTHROPIC_BASE_URL` y variables de proxy: un gateway o proxy local apagado da este mensaje |
| `Can't reach the API server — check your internet or DNS (ENOTFOUND)` o `(FailedToOpenSocket)` | `Unable to connect to API (ENOTFOUND)` | El nombre del servidor no se resuelve | DNS del sistema; en WSL, `/etc/resolv.conf` |
| `No internet route — check your connection or VPN (EHOSTUNREACH)` | `Unable to connect to API (EHOSTUNREACH)` | No hay ruta hasta el servidor | Rutas que haya dejado una VPN; interfaces `utun` en macOS |
| `Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — …` | `Unable to connect to API (ERR_PROXY_TUNNEL)` | El proxy rechazó abrir el túnel | Credenciales del proxy y que permita el host de la API |
| `Request timed out. Check your internet connection and proxy settings` | — | La petición no obtuvo respuesta en el tiempo de espera | Proxy lento o red que descarta paquetes; en redes muy lentas, `API_TIMEOUT_MS` (por defecto 600000 ms) |
| `Unable to connect to API: SSL certificate verification failed (…)` | — | Un proxy o equipo de seguridad intercepta TLS con su propio certificado | `NODE_EXTRA_CA_CERTS` con la CA de tu empresa |
| `anthropic.APIConnectionError: Connection error.` (SDK de Python) | — | Lo mismo desde tu código: no hubo respuesta HTTP | Imprimir `e.__cause__` |

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](https://blog.laozhang.ai/es/posts/claude-code-500-529-rate-limit); para `429`, [Claude Rate Exceeded: qué límite has alcanzado y cómo resolverlo](https://blog.laozhang.ai/es/posts/claude-rate-exceeded-error); para `403` o `503`, [Claude Code 403, 503 y 529: quién da el error y cómo arreglarlo](https://blog.laozhang.ai/es/posts/claude-code-403-503-529-errors); y si falla el inicio de sesión, [Temporarily unable to authenticate en Claude: qué es y qué hacer](https://blog.laozhang.ai/es/posts/claude-temporarily-unable-to-authenticate).

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

Abre [status.claude.com](https://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:

```bash
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:

```bash
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.

![Matriz que cruza el resultado de curl desde la misma shell con el error de Claude Code y señala qué revisar: DNS, firewall o proxy, certificados o entorno](https://blog.laozhang.ai/posts/es/claude-api-error-connection-error/img/route-matrix.webp)

*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.*

| Resultado de curl | Claude Code | Dónde está el fallo |
| --- | --- | --- |
| `Could not resolve host` | `Can't reach the API server … (ENOTFOUND)` | DNS del sistema o resolver de WSL |
| Timeout o conexión rechazada en el puerto 443 | `Connection refused`, `Request timed out` o `Connection dropped` | Firewall, VPN, proxy o ruta de salida |
| Error de certificado (`SSL certificate problem`) | `SSL certificate verification failed` | Inspección TLS sin la CA configurada |
| Cualquier `HTTP/…`, aunque sea `404` | Un error de conexión | Entorno del proceso (`ANTHROPIC_BASE_URL`, settings, WSL, Docker, VPN residual, gateway) o el caso de MTU de algunos operadores |
| Cualquier `HTTP/…` | `401`, `429`, `500`, `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:

| Condición | Lo que imprimió Claude Code |
| --- | --- |
| `ANTHROPIC_BASE_URL=http://127.0.0.1:59999` (puerto sin ningún servicio) | `API Error: Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)` |
| `HTTPS_PROXY=http://127.0.0.1:59998` (puerto de proxy apagado) | El mismo mensaje |
| `ANTHROPIC_BASE_URL=https://api.does-not-exist-laozhang-test.invalid` (dominio inexistente) con una VPN en modo TUN activa | `API Error: Connection dropped (ECONNRESET)`, no `ENOTFOUND` |

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](https://support.claude.com/es/articles/10366432) 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](https://code.claude.com/docs/es/network-config#network-access-requirements).
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](https://github.com/anthropics/claude-code/issues/94225), 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](https://github.com/anthropics/claude-code/issues/100706). 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:

```bash
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:

```bash
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](https://blog.laozhang.ai/es/posts/claude-code-api-configuration).

**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](https://blog.laozhang.ai/es/posts/claude-not-working-in-vscode).

**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`

![Ruta de Claude Code a través de un proxy corporativo con inspección TLS y la CA indicada en NODE_EXTRA_CA_CERTS](https://blog.laozhang.ai/posts/es/claude-api-error-connection-error/img/proxy-ca-path.webp)

*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`:

```bash
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](https://code.claude.com/docs/es/network-config) 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](https://www.anthropic.com/supported-countries): 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.

```python
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:

| `base_url` | `str(e)` | `e.__cause__` |
| --- | --- | --- |
| `http://127.0.0.1:59999` (sin servicio) | `Connection error.` | `ConnectError: [Errno 61] Connection refused` |
| Dominio inexistente con DNS fake-IP de una VPN TUN | `Connection error.` | `ConnectError: [SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol` |

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](https://platform.claude.com/docs/en/api/sdks/python): `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](https://platform.claude.com/docs/en/api/errors) 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](https://blog.laozhang.ai/es/posts/openai-api-error-connection-error).

## 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](https://blog.laozhang.ai/es/posts/claude-api-error-529-overloaded) y [Error 500 en Claude API: cómo reintentar y qué hacer si persiste](https://blog.laozhang.ai/es/posts/claude-api-internal-server-error).

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.

## Fuentes

Páginas externas que cita esta guía, en el orden en que aparecen. Última actualización: 2026-10-21.

- [estado de Claude](https://status.claude.com/) (status.claude.com)
- [referencia de errores de Claude Code](https://code.claude.com/docs/es/errors) (code.claude.com)
- [ayuda de Claude sobre errores de conexión de API](https://support.claude.com/es/articles/10366432) (support.claude.com)
- [requisitos de acceso a la red de Claude Code](https://code.claude.com/docs/es/network-config) (code.claude.com)
- [issue #94225 del repositorio de Claude Code en GitHub](https://github.com/anthropics/claude-code/issues/94225) (github.com)
- [issue #100706 de Claude Code](https://github.com/anthropics/claude-code/issues/100706) (github.com)
- [lista de países donde Anthropic ofrece servicio](https://www.anthropic.com/supported-countries) (anthropic.com)
- [documentación del SDK de Python de Anthropic](https://platform.claude.com/docs/en/api/sdks/python) (platform.claude.com)
- [página de errores de la Claude API](https://platform.claude.com/docs/en/api/errors) (platform.claude.com)