Si Claude API muestra un error de conexión, lo primero es probar si la solicitud llegó a Anthropic. Sin HTTP status, sin cuerpo JSON y sin request-id, trabaja como si fuera un fallo de conexión. Si hay error.type, error.message y request ID, ya no estás en una conexión pura: estás ante un error API devuelto.
Empieza con esta división:
| Lo que ves | Primera acción | Verificación |
|---|---|---|
| Sin respuesta, sin status, sin request ID | Revisa Claude Status actual y luego red, VPN, firewall, proxy, DNS y TLS en la misma ruta. | Reintenta el mismo payload cambiando una sola variable de red. |
El SDK lanza APIConnectionError o APIConnectionTimeoutError | Separa fallo de conexión, timeout de solicitud larga y retry behavior del SDK. | Registra SDK version, timeout, retry count y si la solicitud llegó a la API. |
Claude Code dice API Error: Connection error | Revisa /status, ruta de auth, ANTHROPIC_API_KEY, proxy del terminal, WSL o VS Code. | Ejecuta el mismo comando tras cambiar una sola variable de route/auth. |
| Falla gateway, proxy o provider route | Compara direct Anthropic contra gateway route sin cambiar prompt ni model intent. | Usa el gateway como evidencia de aislamiento, no como prueba de caída global de Anthropic. |
Hay error.type, error.message y request ID | Sal del connection branch y clasifica el HTTP/API error devuelto. | Envía 500, 529 y 429 a sus guías específicas. |
Nota de estado: el 2026-04-30 21:50 Asia/Shanghai, Claude Status mostraba Claude API, Claude Code y Claude Console como operational, mientras claude.ai aparecía con degraded performance. El estado es información en vivo; revisa Claude Status en el momento de tu incidente antes de concluir que el fallo es local.
Regla de parada: conserva el failing path, cambia una sola variable por retry y antes de escalar captura timestamp, region/network, route, SDK class, HTTP status si existe, request ID si existe y resultado del same-path retry.
Empieza por el límite de request ID
En español, "error de conexión en Claude API" suele mezclar varios problemas. Algunos usuarios tienen un firewall corporativo bloqueando api.anthropic.com; otros usan VPN, proxy o WSL; otros ven un timeout del SDK; otros están en Claude Code con una ruta de autenticación distinta; y algunos ya recibieron un 429, 500 o 529 pero siguen llamándolo conexión.
El artículo de Claude Help Center sobre API connection error apunta primero a firewall, network restrictions y VPN. La documentación de Claude API Errors marca el otro lado: los errores devueltos por la API incluyen error.type, error.message, request_id, y las respuestas llevan request-id header. Esa frontera es suficiente para escoger el primer movimiento.
Si no hay respuesta, busca evidencia de conectividad: DNS, TLS, proxy, VPN, firewall, corporate TLS inspection, trust store del runtime, container, CI runner, serverless region o SDK timeout. Si hay request ID, la solicitud tocó la capa API. En ese caso deja de tratarlo como pura conexión y clasifica el status.
Esta frontera evita destruir la señal. Rotar API keys, cambiar de provider, actualizar plan, reinstalar Claude Code o modificar el prompt antes de conocer la ruta puede borrar el síntoma sin explicar la causa. Mantén la misma ruta fallida y cambia una variable por vez.
Triage same-path en 60 segundos
El flujo rápido es concreto:
- Abre Claude Status y confirma el componente: Claude API, Claude Code, Console o claude.ai.
- Mira si el fallo contiene HTTP status, JSON body,
request_idorequest-idheader. - Identifica la ruta real: direct
api.anthropic.com, SDK, Claude Code, corporate proxy, VPN, gateway, provider wrapper, CI o container. - Repite el mismo payload en la misma ruta tras un solo cambio: VPN off, proxy off, otra red, timeout más largo o auth refresh en Claude Code.
- Anota qué cambió, qué se mantuvo igual y si el resultado cambió.
Same-path retry no significa insistir al azar. Si cambias key, prompt, model, network, timeout y provider a la vez, un éxito no te dice qué variable ayudó. Si solo apagas VPN y la misma request funciona, tienes network branch. Si solo aumentas timeout y una long request funciona, tienes timeout branch. Si direct Anthropic funciona y gateway falla, tienes route branch.
La guía de connectivity check de Anthropic sigue la misma forma: API key válida, test request, status code, response body y error messages. No pegues secretos en tickets. Necesitas route, error class, timestamp y retry result, no la clave ni datos privados.
Direct API: red, VPN, firewall, proxy, DNS y TLS
Usa esta rama cuando no hay HTTP status, body ni request ID. El owner puede estar en local host, office firewall, VPN exit, corporate proxy, DNS, TLS certificate, Docker image, CI runner, serverless region o upstream route.
Empieza con pruebas de bajo riesgo:
- Apaga la VPN o cambia a una red directa confiable para un solo retry.
- Compara home network, mobile hotspot, office network y cloud runner en otra región.
- Verifica que firewall, allowlist y proxy rule permitan el endpoint real.
- Comprueba DNS y TLS desde el entorno que falla, no solo desde el browser en otra máquina.
- Si un proxy corporativo termina TLS, revisa el trust store y la CA del runtime.
"Mismo entorno" es la parte crítica. Que el navegador abra una página de ayuda no prueba que backend worker, Docker container, WSL, VS Code Remote, GitHub Actions o serverless function puedan llegar a Claude API. El test debe ejecutarse desde el proceso que envía la request.
Si otra red arregla el mismo payload, no concluyas "Claude está caído". Registra network branch. Si varias redes y hosts independientes fallan al mismo tiempo, y status o reportes públicos apuntan en la misma dirección, entonces una issue de platform-side o regional route se vuelve más plausible. Aun así, deja fecha y hora.
SDK: APIConnectionError, timeout y errores devueltos
El SDK te ayuda a distinguir si hubo respuesta. En la documentación del Python SDK, APIConnectionError significa que la biblioteca no pudo conectar con la API, mientras que APIStatusError indica una respuesta non-2xx. En la documentación del TypeScript SDK, APIConnectionError pertenece a la rama sin HTTP status, y timeout puede aparecer como APIConnectionTimeoutError.
En Python:
hljs pythonimport os
import anthropic
client = anthropic.Anthropic(timeout=60.0, max_retries=2)
try:
message = client.messages.create(
model=os.environ["ANTHROPIC_MODEL"],
max_tokens=256,
messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
except anthropic.APIConnectionError as exc:
print("connection branch", type(exc).__name__, str(exc))
except anthropic.APIStatusError as exc:
print("returned API branch", exc.status_code, exc.response.headers.get("request-id"))
En TypeScript:
hljs tsimport Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({ timeout: 60_000, maxRetries: 2 });
try {
const message = await client.messages.create({
model: process.env.ANTHROPIC_MODEL!,
max_tokens: 256,
messages: [{ role: "user", content: "Say hello in one sentence." }],
});
} catch (error) {
if (error instanceof Anthropic.APIConnectionTimeoutError) {
console.error("timeout branch", error.message);
} else if (error instanceof Anthropic.APIConnectionError) {
console.error("connection branch", error.message);
} else if (error instanceof Anthropic.APIError) {
console.error("returned API branch", error.status, error.headers?.["request-id"]);
}
}
Dos detalles importan. Primero, default retry del SDK puede ocultar el primer intento fallido; registra final failure time, retry count y SDK version. Segundo, long non-streaming requests pueden fallar porque una red intermedia corta conexiones idle. Si el prompt es largo, hay tool calls lentas o una salida grande, prueba streaming o un timeout razonable antes de llamar outage al problema.
APIConnectionError no es rate limit. Si hay HTTP status, cambia de rama: 529 va a Claude API 529 overloaded error, 429 va a Claude API rate-limit reached, y 500 dentro de Claude Code va a Claude Code API Error 500.
Claude Code: terminal route, auth state y entorno
Si el síntoma aparece en Claude Code como API Error: Connection error, no basta con pensar en un script SDK directo. Claude Code puede usar subscription OAuth, API key route, terminal proxy variables, WSL networking, VS Code Remote, corporate terminal proxy o provider wrapper.
Comprueba esto:
- Ejecuta
/statusy anota authentication method y route activos. - Revisa si
ANTHROPIC_API_KEYexiste en shell, IDE, WSL, container o CI que lanzó Claude Code. - Compara
HTTPS_PROXY,HTTP_PROXY,NO_PROXYy custom CA. - Si solo falla en WSL o VS Code Remote, prueba el mismo comando en terminal local.
- No reinstales antes de saber qué ruta usa realmente la herramienta.
La trampa común es asumir que Claude Code siempre usa la ruta de subscription login. Si ANTHROPIC_API_KEY está presente, puede estar usando API-key route. Que el navegador cargue Claude no prueba que el terminal tenga proxy, DNS, certificados y auth correctos.
Si la rama es configuración de ruta, usa la Claude Code API configuration guide. Si el problema devuelto es 500/529/rate limit en Claude Code, cambia al Claude Code 500/529/rate-limit router.
Gateway o provider: prueba de aislamiento, no atajo universal
Un gateway, proxy o provider OpenAI-compatible puede servir como comparación, pero no debe ser la primera explicación. Si puedes probar direct Anthropic, toma ese baseline primero. Luego compara gateway route con el mismo prompt, input size, model intent, timeout y environment.
Si direct funciona y gateway falla, el owner probable es gateway credential, model mapping, proxy o compatibility layer. Si direct falla y gateway funciona, aprendiste que una ruta alternativa llega a una superficie compatible, pero no probaste que el servicio oficial esté caído.
| Prueba | Mantener fijo | Cambiar solo |
|---|---|---|
| Direct Anthropic baseline | prompt, input size, timeout, model intent, environment | route = direct Anthropic |
| Gateway comparison | prompt, input size, timeout, model intent, environment | route = gateway/provider |
| Network comparison | prompt, input size, route, model intent | network, VPN o proxy |
| SDK comparison | prompt, input size, route, model intent | SDK timeout o retry |
Si el resultado cambia, esa variable merece atención. Si no cambia, sigue estrechando el diagnóstico.
Cuando ya no es un error de conexión
En cuanto tienes HTTP status, JSON body o request ID, la request llegó a la capa API. Conserva el request ID y clasifica el returned error.
| Señal devuelta | Clase oficial | Siguiente rama |
|---|---|---|
429 | rate_limit_error | Claude API rate-limit reached |
500 | api_error | Para Claude Code: API Error 500 |
504 | timeout_error | timeout o long request antes de cambiar auth |
529 | overloaded_error | Claude API 529 overloaded error |
El error frecuente es seguir llamando "conexión" a un 429 o 529 devuelto. Eso mueve la reparación en dirección incorrecta. 429 necesita rate-limit handling, 529 necesita overload-aware retry, 500 necesita otra historia de escalation y un DNS failure necesita network branch.
Paquete mínimo para escalar
Escala cuando el mismo path sigue fallando después de revisar status, request-id boundary, route owner y un same-path retry. El paquete debe ser corto, pero suficiente para que soporte o tu platform team clasifique la rama.
Incluye:
- timestamp y timezone;
- SDK name, SDK version, runtime, host y region;
- exact error string y exception class;
- HTTP status,
error.type,error.messagey request ID si existen; - active route: direct Anthropic, Claude Code, gateway, proxy, VPN, CI, WSL, container o browser;
- qué mostraba Claude Status en ese momento;
- resultado de same-path retry tras un cambio específico;
- reproducción mínima con secretos eliminados.
No envíes API keys, private prompts, customer records, proxy logs con credenciales ni request body completo. Un buen informe no es largo; deja claro qué rama ya probaste y qué fallo persiste.
Preguntas frecuentes
¿Qué significa normalmente un error de conexión de Claude API?
Si no hay status code, body ni request ID, suele significar que el cliente no completó la ruta hacia la API. Revisa status, network, VPN, firewall, proxy, DNS/TLS, SDK timeout y route ownership.
¿Debo rotar la API key primero?
Normalmente no. Para un no-response connection error, key rotation es mala primera acción. Primero prueba si la request llegó a la API y repite la misma ruta tras un cambio de red, timeout o auth.
¿Claude Status en verde prueba que el fallo es local?
No. Solo reduce la probabilidad de un live incident en ese componente. Tu network, SDK, Claude Code route, gateway o regional path pueden seguir fallando.
¿Por qué el SDK muestra APIConnectionError sin HTTP status?
Porque el SDK no recibió una respuesta normal de la API. Mira connectivity, proxy, DNS/TLS, VPN, firewall, timeout y route ownership.
¿API Error: Connection error en Claude Code es lo mismo?
Comparte la frontera de request ID, pero Claude Code añade /status, ANTHROPIC_API_KEY, terminal proxy, WSL, VS Code y auth route.
¿Cuándo usar gateway route?
Cuando direct access está bloqueado o necesitas una segunda ruta compatible para comparar. Mantén prompt, input size, model intent y timeout, y cambia solo route.
¿Qué envío a soporte?
Timestamp, route, SDK/runtime, exact error, HTTP status, request ID, status page note, same-path retry result y redacted reproduction. La evidencia con rama clara es más útil que una queja general.
Regla práctica
Un error de conexión de Claude API sigue siendo un problema de reachability hasta que la request produce una respuesta. Revisa status actual, conserva el request-id boundary, elige direct API, SDK, Claude Code, network/proxy o gateway branch, cambia una sola variable y reintenta el mismo path. Si persiste, escala con el evidence packet mínimo.
