Índice
¿Intentas usar Claude Code en un equipo corporativo o a través de una VPN y no consigue conectar, con errores como estos?
Unable to connect to API. Check your internet connection
Unable to connect to API (ECONNREFUSED)
Unable to connect to API: SSL certificate verification failed.
Check your proxy or corporate SSL certificates
fetch failedEstos son errores de red que significan "Claude Code no puede alcanzar el servidor de Anthropic (api.anthropic.com)." No son de autenticación (401/403), ni de sobrecarga del servidor (529/500), ni un límite de tasa (429): la solicitud nunca llegó al servidor. Las causas habituales son los proxies corporativos, la inspección TLS (certificados) y los firewalls, lo que lo hace especialmente frecuente en redes empresariales. Este artículo cubre la configuración del proxy, los certificados CA corporativos, los dominios a permitir y los pasos de diagnóstico, basándose en información oficial.
Puntos clave por adelantado. (1) Detrás de un proxy, configura HTTPS_PROXY. (2) Ante un error de certificado por inspección TLS (Zscaler, etc.), apunta NODE_EXTRA_CA_CERTS a la CA corporativa y nunca desactives la verificación con NODE_TLS_REJECT_UNAUTHORIZED=0 (expone todo el tráfico a interceptación). (3) Empieza ejecutando curl -I https://api.anthropic.com para comprobar "¿siquiera llega?": ese es el punto de partida del diagnóstico.
Nunca llega al servidor
— dónde se detiene decide la solución
HTTPS_PROXYNODE_EXTRA_CA_CERTS
Primero ejecuta curl -I https://api.anthropic.com para comprobar si puede llegar.
Una vez sepas dónde se detiene (proxy / TLS / firewall), queda decidido qué ajuste aplicar.
1. Qué te está diciendo este error
Unable to connect to API, fetch failed, ECONNREFUSED / ETIMEDOUT significan "la solicitud no llegó al servidor de Anthropic" = falló en algún punto de TCP/TLS/DNS. Esta es la diferencia decisiva frente a otros errores: autenticación (401/403), servidor (529/500) y tasa (429) son respuestas tras haber alcanzado el servidor, mientras que los errores de red significan que nunca llegó allí.
En redes empresariales, los bloqueos típicos se dividen en tres capas. (1) Proxy: no puedes salir directamente y debes pasar por un proxy corporativo que no está configurado. (2) Inspección TLS (certificados): un proxy de inspección como Zscaler reemplaza los certificados, así que debes confiar en la CA raíz corporativa. (3) Firewall: los dominios necesarios no están permitidos. Lo primero que hay que hacer es confirmar "¿puede llegar?" con curl -I https://api.anthropic.com: esta única comprobación separa "un problema de red" de "todo lo demás."
Dónde se detiene = qué ajuste aplicar
ECONNREFUSED/ETIMEDOUT/fetch failed. Debes pasar por el proxy corporativo → configura HTTPS_PROXY.SSL certificate verification failed/self-signed → pon la CA corporativa en NODE_EXTRA_CA_CERTS. Nunca desactives la verificación.Could not resolve host/ENOTFOUND. DNS caído, VPN obsoleta o Docker interceptando el tráfico.
Si curl -I https://api.anthropic.com tiene éxito, el problema se reduce a algo entre Claude Code y la red.
2. Configuración del proxy (HTTPS_PROXY)
Cuando debes pasar por un proxy corporativo, configura las variables de entorno de proxy estándar. Claude Code las respeta.
# Recomendado: proxy HTTPS
export HTTPS_PROXY=http://proxy.example.com:8080
# Si HTTPS no está disponible, HTTP_PROXY
export HTTP_PROXY=http://proxy.example.com:8080
# Destinos que omiten el proxy (separados por espacios o comas)
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"
# Proxy con autenticación (evita codificar contraseñas en duro)
export HTTPS_PROXY=http://username:password@proxy.example.com:8080Advertencias: los proxies SOCKS no son compatibles. Para proxies NTLM / Kerberos, la recomendación oficial es montar un LLM gateway en medio y apuntar ANTHROPIC_BASE_URL a él. Además, si usas servidores MCP, debes configurar explícitamente HTTPS_PROXY y NODE_EXTRA_CA_CERTS en el env de cada servidor (no se heredan del padre). Estas variables también pueden ir en el bloque env de settings.json.
3. TLS y certificados CA corporativos (lo más importante, de forma segura)
El bloqueo empresarial más común es un error de certificado provocado por un proxy de inspección TLS (Zscaler, Netskope, Palo Alto, etc.) que reemplaza los certificados. Los mensajes típicos son unable to get local issuer certificate y SELF_SIGNED_CERT_IN_CHAIN.
Como contexto, las versiones recientes de Claude Code confían TANTO en su conjunto de CA incluido COMO en el almacén de confianza del sistema operativo. Por eso, si la CA raíz corporativa está en el almacén de certificados del sistema operativo, a menudo funciona sin configuración adicional (el comportamiento varía según la versión, así que confirma la más reciente). Si no está en el almacén del sistema operativo, apunta NODE_EXTRA_CA_CERTS al paquete de CA (PEM) que recibiste de TI:
# La forma correcta y segura: confiar en la CA corporativa
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
# Si el proxy requiere un certificado de cliente (mTLS)
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem⚠️ NO hagas: desactivar la verificación TLS
Desactivar la verificación de certificados con NODE_TLS_REJECT_UNAUTHORIZED=0 parece "arreglarlo", pero nunca lo hagas. Desactiva la verificación TLS de todo el proceso, de modo que todo el tráfico — incluido el dirigido a api.anthropic.com — queda expuesto a ataques de intermediario (escucha/manipulación). Eso arriesga filtrar credenciales y código. La respuesta correcta siempre es "confiar adecuadamente en la CA corporativa mediante NODE_EXTRA_CA_CERTS."
Si te topas con un error de certificado en el momento de la instalación (antes de que exista el binario), pasa la CA a curl: curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash.
4. Dominios a permitir en el firewall
Si tu firewall restringe los destinos, permite estos dominios sobre HTTPS (443) (según los requisitos de red oficiales).
| Dominio | Para qué sirve |
|---|---|
api.anthropic.com | Solicitudes a la API de Claude (obligatorio) |
claude.ai | Autenticación de cuenta de claude.ai |
platform.claude.com | Autenticación de cuenta de la Consola |
downloads.claude.ai | Instalador, actualización automática, plugins |
raw.githubusercontent.com | Notas de versión, marketplace |
La telemetría (statsig.anthropic.com) y el reporte de errores (*.sentry.io) son opcionales y se pueden desactivar (no es necesario incluirlos en la lista de permitidos obligatoria). Si gestionas las instalaciones por tu cuenta vía npm, es posible que no necesites downloads.claude.ai. Los dominios y rangos de IP exactos pueden cambiar, así que confirma lo más reciente en la página oficial de configuración de red.
5. El flujo de diagnóstico
Cuando no consigue conectar, ve de arriba abajo. El primer curl marca la dirección.
Aíslalo de arriba abajo
curl -I https://api.anthropic.com (Windows: curl.exe) para probar la accesibilidad. Si pasa, el problema está de tu lado./doctor (o claude doctor si no arranca) y comprueba las variables de entorno del proxy.NODE_EXTRA_CA_CERTS; sin proxy configurado → aplica HTTPS_PROXY.curl pasa pero Claude Code falla, sospecha del DNS (resolv.conf de WSL), una VPN obsoleta o Docker interceptando el tráfico.
La regla: "prueba primero la accesibilidad (curl) y luego aplica el ajuste de la capa que te detuvo."
Gestiona los certificados con NODE_EXTRA_CA_CERTS. Nunca desactives la verificación.
6. Cómo distinguirlo de errores parecidos
"Se detuvo" también puede no ser de red. La gran división es "¿llegó al servidor?"
| Síntoma | Qué es en realidad | Solución principal |
|---|---|---|
| Unable to connect / fetch failed / error de certificado | Este artículo = red (nunca llegó al servidor) | HTTPS_PROXY / NODE_EXTRA_CA_CERTS / lista de permitidos del firewall |
| 401 / 403 / Invalid API key | Autenticación (llegó, pero hay un problema de credenciales) | errores de autenticación / inicio de sesión |
| 529 / 500 | Del lado del servidor (llegó, pero está sobrecargado / error interno) | errores 529/500 |
| 429 Request rejected | Límite de tasa (llegó, pero demasiado tráfico) | Reduce el ritmo, espera |
Una regla mnemotécnica: los errores de red significan "nunca llegó al servidor" (TCP/TLS/DNS), y HTTPS_PROXY o NODE_EXTRA_CA_CERTS solo ayudan en esta capa. En cambio, 401/403, 529/500 y 429 son "respuestas tras haber llegado", así que ajustar el proxy o la CA no los resolverá. Que curl tenga éxito o no es la mejor señal para separar ambos casos. Para otros errores comunes, consulta el recopilatorio de errores.
Resumen
Los errores de red/proxy de Claude Code (Unable to connect / fetch failed / SSL certificate verification failed, etc.) significan que la solicitud nunca llegó al servidor = un fallo de TCP/TLS/DNS. Son distintos de los de autenticación (401/403), servidor (529/500) y tasa (429), y los culpables habituales son el proxy, la inspección TLS y el firewall empresariales.
Las soluciones: (1) detrás de un proxy, configura HTTPS_PROXY (SOCKS no compatible; NTLM/Kerberos mediante un gateway), (2) ante errores de certificado pon la CA corporativa en NODE_EXTRA_CA_CERTS — nunca NODE_TLS_REJECT_UNAUTHORIZED=0, (3) permite api.anthropic.com etc. en el firewall. Diagnostica probando primero la accesibilidad con curl -I https://api.anthropic.com -> /doctor y comprobación del proxy -> ajustes de certificado/proxy -> una conexión directa para confirmar -> DNS/VPN/Docker. La clave es separar red de autenticación/servidor/tasa según "¿llegó al servidor?" Relacionados: errores de autenticación / inicio de sesión, errores 529/500, recopilatorio de errores de Claude Code.
FAQ
Q. En el PC de mi empresa me sale "Unable to connect to API" y no consigo conectar.
A. Normalmente debes pasar por un proxy corporativo que no está configurado. Primero comprueba la accesibilidad con curl -I https://api.anthropic.com; si falla, configura un proxy como export HTTPS_PROXY=http://proxy.example.com:8080 (añade user:password@ para un proxy con autenticación). Ten en cuenta que SOCKS no es compatible, y para proxies NTLM/Kerberos la recomendación oficial es pasar por un LLM gateway.
Q. Me sale "SSL certificate verification failed".
A. Esto suele ser un proxy corporativo de inspección TLS (p. ej., Zscaler) que reemplaza los certificados. Consigue la CA raíz corporativa (PEM) de TI y configura export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem. Si la CA corporativa ya está en el almacén de certificados del sistema operativo, puede que funcione sin configuración. Nunca desactives la verificación con NODE_TLS_REJECT_UNAUTHORIZED=0: eso expone todo el tráfico a interceptación.
Q. Poner NODE_TLS_REJECT_UNAUTHORIZED=0 lo arregló. ¿Está bien?
A. No: revíertelo ahora mismo. Desactiva la verificación de certificados TLS en todo el proceso, dejando todo el tráfico — incluido el dirigido a api.anthropic.com — indefenso ante ataques de intermediario (escucha/manipulación). Es un riesgo de seguridad grave que puede filtrar credenciales y código fuente. La única solución correcta es confiar adecuadamente en la CA corporativa mediante NODE_EXTRA_CA_CERTS.
Q. ¿Qué dominios debo permitir en el firewall?
A. Sobre HTTPS (443), como mínimo permite api.anthropic.com (API), claude.ai y platform.claude.com (autenticación), downloads.claude.ai (instalador/actualizaciones) y raw.githubusercontent.com. La telemetría (statsig) y el reporte de errores (sentry) son opcionales. Los dominios/IP exactos pueden cambiar, así que confirma lo más reciente en la página oficial de configuración de red.
Q. curl funciona, pero solo Claude Code no consigue conectar.
A. La causa suele estar entre Claude Code y el sistema operativo. Casos comunes: un /etc/resolv.conf de WSL que apunta a un DNS caído, restos de una VPN obsoleta (p. ej., interfaces utun antiguas de macOS), o una herramienta residente como Docker interceptando el tráfico. Prueba una conexión directa sin VPN, detén las herramientas residentes y revisa el DNS, en ese orden. Ten en cuenta que los errores 5xx transitorios se reintentan automáticamente hasta 10 veces, así que si ves un error mientras curl tiene éxito, los reintentos ya se han agotado.
