Errores de API de IA: 401, 429, 5xx y tiempos de espera agotados
Distingue autenticación, cuota, límites de solicitudes y fallos transitorios en las API de OpenAI, Claude y Gemini. Usa los detalles del error antes de decidir reintentar.
Respuesta rápida
Un error de API no demuestra por sí solo una interrupción del proveedor. Lee el cuerpo del error y el ID de solicitud del proveedor y luego comprueba el componente de estado correspondiente. Los problemas de autenticación y facturación requieren cambios de configuración; los fallos transitorios pueden justificar reintentos limitados.
Empieza por la categoría del error
Usa esta tabla para elegir una primera comprobación. Los significados y soluciones exactos dependen del proveedor, punto de conexión y cuerpo del error.
| Lo que ves | Primera comprobación | Lo que no establece |
|---|---|---|
| 400 / 404 / 413 | Formato de solicitud, punto de conexión, recurso y tamaño; lee el error del proveedor | Una interrupción general del servicio |
| 401 / 403 | Credenciales, permisos de acceso y restricciones del proveedor | Que todos los usuarios estén bloqueados |
| 429 | Cabeceras de límites de solicitudes, cuota, créditos y límites de gasto | Que reintentar inmediatamente funcione |
| 500 / 503 / 529 | Detalles de error del proveedor y componente oficial pertinente | Un incidente global confirmado |
| Tiempo de espera agotado / error de conexión | Plazo del cliente, DNS, TLS, proxy y duración de solicitud | Qué lado causó el fallo |
OpenAI: un 429 puede significar límites distintos
Examina error.code, no solo HTTP 429. OpenAI distingue los límites de frecuencia de solicitudes de los créditos agotados y límites de organización o proyecto. Los fallos de facturación y cuota no se corrigen reintentando. Para límites transitorios o sobrecarga, respeta Retry-After cuando esté presente y limita los reintentos.
Usa la entrada OpenAI API para componentes API. La entrada de aplicación ChatGPT no confirma el resultado de una solicitud API ni el estado de un modelo GPT específico.
Claude: sobrecarga y topes de gasto son distintos
Claude documenta 529 como sobrecarga, 401 como fallo de autenticación y 403 como fallo de permisos. Un 429 puede reflejar límites de solicitudes o un tope de gasto. Un 429 por tope de gasto del nivel de uso no incluye cabecera Retry-After y sigue fallando hasta que se restablece el acceso. Lee el error completo antes de elegir una política de reintentos.
Para respuestas en flujo, Claude documenta que un error puede ocurrir después de HTTP 200. Comprueba la finalización y los eventos de error del flujo; recibir solo las cabeceras de respuesta no demuestra una generación exitosa.
Gemini: verifica el punto de conexión para desarrolladores
Google recomienda espera exponencial limitada con variación aleatoria para fallos transitorios. Comprueba también la versión de API, el modelo y los parámetros admitidos. Consulta el informe propio de la API para desarrolladores; el flujo de incidentes de la aplicación Gemini no abarca solicitudes de Gemini API o AI Studio.
Asigna un presupuesto a los reintentos
Como decisión de diseño de la aplicación, establece un máximo de intentos y un presupuesto total de tiempo. Ten en cuenta los reintentos ya realizados por tu SDK. Usa un retraso con espera exponencial y variación aleatoria para errores que el proveedor identifica como transitorios, y respeta las cabeceras de reintento aplicables.
Antes de repetir una solicitud interrumpida, comprueba si ya pudo haber generado una salida, un cargo o una acción posterior. Reintentar una solicitud de modelo y repetir la acción de una herramienta de un agente son decisiones independientes. Conserva los ID de solicitud para investigar y detén los reintentos automáticos al agotar el presupuesto permitido.
Soluciona problemas de una respuesta específica
Usa una guía dedicada al error devuelto por tu solicitud. Estas páginas explican fallos de solicitudes; no monitorean límites de cuenta.
Páginas de servicios relacionados
Cada entrada muestra su propia cobertura de recopilación. Un servicio enlazado no se recopila necesariamente de forma automática.
La fecha de revisión editorial corresponde a esta guía. Las horas de recopilación de informes actuales aparecen en las páginas de servicio.