Errores de API de IA: 401, 403, 429 y 5xx
Diagnostica por capas autenticación, políticas, límites, cancelaciones y fallos upstream, y decide cuándo es seguro reintentar.
Un código de estado inicia el diagnóstico de una API de IA, pero no explica por sí solo la causa. Antes de reintentar, guarda ID de petición, hora UTC, endpoint, modelo, nombre de clave, grupo elegido, error estructurado y tiempos. Así podrás ubicar el rechazo en cliente, autenticación, política, protocolo, ruta, backend o conexión downstream.
Interpretación inicial
| Estado | Primera lectura | Acción inicial |
|---|---|---|
| 400 | Payload o protocolo no válido | Corrige; no repitas igual |
| 401 | Credencial ausente, inválida o caducada | Revisa Authorization y la clave actual |
| 403 | Política de cuenta, modelo, grupo o IP | Comprueba restricciones antes de canales |
| 404 | Ruta o modelo incorrecto | Verifica Base URL y /v1/models |
| 429 | Límite de cuota, tasa o ruta | Localiza el límite y aplica espera acotada |
| 499 | El cliente canceló antes de terminar | Revisa deadlines, abortos, proxies y primer resultado |
| 502/503/504 | Respuesta upstream, disponibilidad o tiempo | Conserva evidencia y reintenta de forma limitada |
Diagnostica por capas
Un 401 suele ocurrir antes del enrutamiento. Verifica Authorization: Bearer ..., estado de la clave, host y secretos antiguos en el despliegue. Nunca copies la clave completa a logs o tickets.
Un 403 no demuestra un rechazo del proveedor: límites de modelo, lista de IP, acceso a grupos o política de cuenta pueden actuar antes de elegir canal. Consulta /v1/models con la misma clave y el código exacto.
Ante 429, identifica si el límite pertenece a clave, cuenta, grupo o ruta. Respeta Retry-After, usa backoff exponencial con jitter y limita intentos, duración y concurrencia. Más claves no eluden necesariamente un límite de cuenta.
Un 499 registra que la conexión downstream terminó. Empieza por Abort, navegador, CDN, balanceador y proxy; compara el primer resultado efectivo. Una sola fila no prueba una caída del canal.
Cuándo reintentar
- Payload, credencial o acceso inválido: corrige, no repitas igual.
- Rate limit: backoff acotado solo cuando esté permitido.
- 502, 503 o 504 temporal: reintenta únicamente trabajo idempotente con presupuesto estricto.
- Cancelación: confirma que aún se necesita y que no duplica efectos.
- Herramientas o escrituras: exige idempotencia de aplicación.
Cada intento puede generar trabajo y coste. Comparte de forma segura ID, hora, endpoint, streaming, modelo, grupo, estado, código y tiempos; evita clave completa, prompt, respuesta, cuerpo original, correo o IP en claro. Después usa Enrutamiento fiable y la guía de streaming para corregir la capa encontrada.