openai.APIConnectionError: Connection error significa que el SDK no pudo completar la ruta hacia el endpoint configurado. Si no tienes HTTP status, cuerpo JSON ni request ID, empieza por la ruta entre tu runtime y OpenAI. No cambies keys, billing, modelo o prompt hasta saber si la petición llegó a un servidor.
Si ya hay status, cambia el dueño. Un 401 es autenticación, un 429 es cuota o rate limit, y un 500/503 es una rama de servidor o disponibilidad temporal. La rama sin respuesta va primero cuando la petición falló antes de traer evidencia útil del API. Al comprobarlo el 6 de mayo de 2026, OpenAI Status estaba operativo, y la documentación oficial de errores de OpenAI describe APIConnectionError como un problema de conexión que exige revisar red, proxy, certificados SSL, firewall y permisos de contenedor.
Decisión rápida
| Evidencia | Dueño inicial | Siguiente paso |
|---|---|---|
| Sin status, body ni request ID | Ruta de conexión | Prueba status, DNS, TLS, proxy, firewall y egreso desde el mismo runtime. |
| 401 devuelto | Autenticación | Revisa key, project, organization y tipo de endpoint. |
| 429 o rate headers | Cuota/rate | Usa la rama de cuota o rate limit, no diagnóstico de conexión. |
| 500/503 con request ID | API/server | Conserva request ID, retry limitado y status. |
| Azure o gateway | Provider route | Verifica base URL, deployment, provider status y outbound HTTPS. |
Lee primero la evidencia de respuesta
APIConnectionError importa porque muchas veces el SDK no tiene una respuesta del servidor que clasificar. Los SDK actuales separan connection failures de APIStatusError, que aparece cuando hubo una respuesta 4xx o 5xx. Por eso la ausencia de status es evidencia.
Busca la causa subyacente: remote disconnect, DNS failure, TLS certificate error, proxy error o timeout. Si ves 429, insufficient_quota o rate headers, pasa a OpenAI API rate limits o a la rama de cuota. Mezclar todo en un consejo de retry oculta el dueño real.
Prueba la misma ruta en 10 minutos
Ejecuta las pruebas desde la misma máquina, contenedor, función serverless, worker, región y base URL que falló. Una prueba local solo demuestra la ruta local.
- Abre https://status.openai.com/ y registra la hora.
- Comprueba DNS para el host real.
- Comprueba TLS 443 desde el mismo runtime.
- Verifica que no mezclas direct OpenAI, Azure OpenAI y gateway.
- Revisa proxy, VPN, firewall, WAF o NAT.
- Compara local y deploy solo con la misma key, model, endpoint y env vars.
Anota dónde cambia la evidencia. DNS, TLS, proxy refusal, remote disconnect y timeout no se arreglan igual.
Controles SDK que conservan evidencia
En Python, captura APIConnectionError separado de APITimeoutError y APIStatusError. Durante el diagnóstico, define timeout, reduce max_retries y usa OPENAI_LOG=debug solo el tiempo necesario para capturar la causa. En Node, maxRetries, timeout, request IDs, raw response y proxy fetch cumplen el mismo papel.
No uses retries infinitos. Un proxy bloqueado, un CA bundle roto, un base URL equivocado o un egress cerrado no se corrigen con más intentos. Mantén una petición mínima por la misma ruta como probe.
Ramas de ruta
Con direct OpenAI, prueba primero la ruta a api.openai.com. En Azure OpenAI revisa resource endpoint, deployment name, API version, region routing y reglas de red. Un gateway compatible con OpenAI debe tratarse como provider route hasta que una prueba directa demuestre el mismo síntoma.
Las llamadas desde navegador son otra rama: CORS, keys expuestas, networking del navegador y diseño de proxy pueden ser el owner. En producción, mueve la llamada server-side antes de diagnosticar el SDK como backend.
Paquete de escalación
Antes de escalar, reúne timestamp y zona horaria, endpoint/base URL, SDK y versión, modelo, runtime y región, ruta direct OpenAI o Azure/gateway, excepción subyacente, existencia de status/body/request ID y logs saneados. No incluyas API keys, headers secretos ni datos de clientes.
Una frase útil sería: status page revisado el 2026-05-06 22:40 CST, DNS funciona dentro del contenedor, TLS falla con corporate CA, no hay request ID. Eso ayuda más que una captura aislada.
Si tu equipo tiene local dev, staging, production worker y jobs por región, añade una mini matriz con runtime, proxy profile, base URL y resultado mínimo. APIConnectionError suele aparecer solo en una ruta porque cambian egress, DNS resolver o CA bundle. Esa matriz evita que alguien corrija prompts, modelos o cuotas cuando el propietario real está en red o runtime.
FAQ
APIConnectionError significa que OpenAI está caído?
No. Significa que tu petición no completó la ruta de conexión. DNS, TLS, proxy, firewall, container egress, endpoint o gateway pueden ser el owner.
Por qué no hay request ID?
Normalmente porque la petición no llegó al punto donde la API podía devolver una respuesta.
Debo cambiar la API key?
No primero. Si vuelve 401, revisa auth. Si no hay respuesta, revisa la ruta.
Es lo mismo que rate limit?
No normalmente. Si hay 429 o rate headers, usa OpenAI API rate limits.