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.
Comprobaciones específicas por capa
Para un 401
Verifica Authorization: Bearer ..., que no haya comillas ni espacios añadidos, que la clave siga activa y que el despliegue no conserve una versión anterior. Este fallo suele preceder al enrutamiento del modelo.
Para un 403
Revisa modelos permitidos, lista de IP, acceso al grupo y política de cuenta con la misma clave. Si todavía no se eligió canal, cambiar proveedores no corrige el rechazo anterior.
Para un 429
Identifica si el límite pertenece a la clave, la cuenta, el grupo o la ruta. Respeta Retry-After, aplica espera exponencial con variación y limita intentos, duración y concurrencia.
Para un 499
Empieza por el cliente: señal de cancelación, pestaña cerrada, CDN, balanceador y tiempos máximos del proxy. Compara el instante de cancelación con el primer resultado efectivo; un 499 aislado no prueba una caída del canal.
Diferencia los errores 5xx
Un 500 puede ser un fallo determinista de adaptación, un 502 una respuesta upstream inválida o incompleta, un 503 falta temporal de ruta y un 504 el agotamiento de un presupuesto de tiempo. Conserva el estado original y solo repite operaciones seguras con un límite estricto.
Evidencia segura para el diagnóstico
- ID de petición y hora UTC;
- endpoint y modo de transmisión;
- modelo solicitado y grupo seleccionado;
- estado HTTP y código de error estructurado;
- tiempo total y tiempo al primer resultado efectivo;
- indicación de cancelación del cliente;
- descripción saneada de funciones como herramientas o imágenes.
No incluyas la clave completa, el prompt, la respuesta, el cuerpo original, correo o IP en claro salvo que exista un proceso seguro expresamente aprobado.
Preguntas frecuentes
¿Un 403 demuestra que el proveedor está caído?
No. Cuenta, clave, modelo, grupo, IP o política de funciones pueden rechazar la petición antes de seleccionar un proveedor.
¿Un 499 es un error estándar del modelo upstream?
No. En los registros de Modelflare representa una cancelación downstream observada antes de completar la respuesta.
¿Debe reintentarse cualquier 5xx?
No. Repite únicamente trabajo seguro, con número de intentos y tiempo total limitados, y conserva siempre el primer error.