Guía de errores de API de IA: 401, 403, 429 y 5xx

Diagnostica fallas de autenticación, políticas de acceso, límites de frecuencia, cancelaciones del cliente y errores del proveedor, y decide cuándo es seguro reintentar.

Guía de errores de API de IA: 401, 403, 429 y 5xx

Los errores de una API de IA son más fáciles de diagnosticar cuando el código de estado se toma como el inicio de la investigación y no como la causa completa. Antes de reintentar, conserva el ID de la solicitud, la marca de tiempo, el endpoint, el modelo, el nombre de la clave de API, el grupo seleccionado, el cuerpo de la respuesta y los tiempos.

El objetivo es identificar qué capa rechazó o terminó la solicitud: el cliente, la autenticación, la política de acceso, la validación del protocolo, el enrutamiento, el backend del modelo o la conexión downstream.

Qué suelen indicar los códigos de estado más comunes

Estado Primera interpretación Primera acción
400 Estructura, campo o contrato de protocolo de la solicitud no válido Compara el payload con el endpoint seleccionado; no reintentes sin cambios
401 Credencial ausente, mal formada, deshabilitada, vencida o no válida Verifica el encabezado Authorization y la clave vigente
403 Autenticada, pero bloqueada por la cuenta, el modelo, el grupo, la IP o una política Revisa las restricciones de la clave y el acceso al modelo o grupo antes de probar canales
404 Ruta de endpoint incorrecta o identificador de modelo no disponible Verifica la URL base, la ruta y la lista autenticada de modelos
429 Límite de frecuencia de solicitudes, de créditos o de rutas aptas Revisa los créditos y los límites del grupo; usa un backoff acotado o el respaldo configurado
499 El cliente downstream se desconectó o canceló antes de completarse la solicitud Revisa los plazos límite del cliente, las cancelaciones, los proxies y el tiempo hasta la primera salida
500 Falla interna de procesamiento o del adaptador Conserva el ID de la solicitud; reintenta solo si la operación es segura
502/503 Respuesta incorrecta del proveedor, ruta no disponible o problema temporal de capacidad Revisa la evidencia de la ruta y usa un respaldo o reintento acotado
504 Venció un margen de tiempo del gateway o del proveedor Compara los tiempos de primera salida y total con los plazos límite del cliente

Estas interpretaciones son puntos de partida para el diagnóstico. El cuerpo del error y el registro de la solicitud determinan el motivo real de cada llamada.

Diagnostica el 401 antes de cambiar el modelo

Un 401 normalmente ocurre antes de cualquier enrutamiento útil del modelo. Verifica que:

  • el encabezado use Authorization: Bearer ...;
  • la aplicación no haya incluido comillas, espacios en blanco ni un valor de marcador de posición;
  • la clave esté habilitada y no haya vencido;
  • la solicitud se envíe al host de Modelflare previsto;
  • un administrador de secretos o un despliegue no conserve una clave anterior ya rotada.

No pegues la clave completa en registros ni en mensajes a soporte. Si existe riesgo de exposición, reproduce el problema con una clave de prueba dedicada y luego revoca la credencial comprometida.

Diagnostica el 403 primero como una falla de política de acceso

Un 403 no significa automáticamente que el proveedor haya rechazado la solicitud. La autenticación puede funcionar y el acceso puede fallar antes de seleccionar un canal porque:

  • la clave restringe el modelo solicitado;
  • la lista de IP permitidas de la clave no incluye la IP del cliente observada;
  • la cuenta no puede usar el grupo de modelos seleccionado;
  • una política deshabilitó al usuario o la clave;
  • la función solicitada no está permitida para esa ruta.

Consulta /v1/models con la misma clave, revisa sus límites de grupo y de modelos, y compara el código de error exacto. Si no se seleccionó ningún canal, cambiar los canales del proveedor no puede corregir la decisión de política anterior.

Diagnostica el 429 sin provocar una tormenta de reintentos

Un 429 es una señal de capacidad o de política, no una instrucción para reintentar de inmediato en un ciclo cerrado. Determina si el límite corresponde a los créditos de la clave, a la cuenta, al grupo de modelos o a la ruta seleccionada.

Para los límites de frecuencia que se pueden reintentar:

  1. respeta Retry-After cuando esté presente;
  2. usa backoff exponencial con jitter;
  3. limita la cantidad de intentos y el tiempo total transcurrido;
  4. mantén la concurrencia de la aplicación dentro de un límite conocido;
  5. usa grupos de respaldo ordenados solo cuando conserven el modelo y el protocolo solicitados.

Crear más claves de API no evita necesariamente un límite de solicitudes de la cuenta o del grupo.

Diagnostica el 499 desde quien hace la llamada hacia afuera

Modelflare puede registrar 499 cuando la conexión del cliente downstream termina antes de que se complete la respuesta. Empieza por quien hace la llamada:

  • ¿Se activó una señal de cancelación?
  • ¿El cliente, el balanceador de carga, la CDN o el proxy inverso alcanzó un tiempo de espera por inactividad o total?
  • ¿El usuario cerró la página o detuvo el agente?
  • ¿El flujo produjo un evento de herramienta sin texto visible?
  • ¿Cuánto tiempo pasó antes de la primera salida efectiva?

Un registro 499 por sí solo no demuestra una caída del canal. Compara otras solicitudes del mismo período y del mismo modelo y grupo antes de cambiar la política de enrutamiento.

Separa las fallas 5xx por capa

Ante un 5xx, conserva el estado original y los detalles del error, en lugar de convertir todas las fallas en un 500 genérico en el cliente.

  • Un 500 de validación o del adaptador puede ser determinista y volver a fallar si no cambias nada.
  • Un 502 puede indicar una respuesta del proveedor no válida o incompleta.
  • Un 503 puede indicar que no hay ninguna ruta apta o que hay una falta de disponibilidad temporal.
  • Un 504 indica que venció un margen de tiempo, pero todavía hay que identificar la capa responsable.

Usa los tiempos de la solicitud, el grupo seleccionado, la evidencia del canal disponible para soporte y las solicitudes cercanas para distinguir una sola respuesta incorrecta de un problema sostenido de la ruta.

Decide si conviene reintentar

Tipo de falla Decisión predeterminada sobre el reintento
Payload no válido o protocolo no admitido Corrige la solicitud; no reintentes sin cambios
Clave no válida o acceso denegado Corrige las credenciales o la política; no reintentes sin cambios
Créditos agotados Aumenta o reasigna los créditos de forma intencional; no repitas en ciclo
Límite de frecuencia Reintenta con backoff acotado cuando esté permitido
502/503/504 temporal Reintenta el trabajo idempotente con un límite estricto de intentos
Cancelación del cliente Reintenta solo si el usuario aún necesita el resultado y los duplicados son seguros
Efecto secundario de herramienta o escritura Exige idempotencia a nivel de aplicación antes de repetir

Los reintentos generan trabajo nuevo y pueden generar costos nuevos. Registra cada intento y evita que un éxito posterior oculte la falla original.

Evidencia que puedes registrar de forma segura

Para soporte o para la revisión de un incidente, registra:

  • el ID de la solicitud y la marca de tiempo en UTC;
  • el endpoint y el modo de streaming;
  • el modelo solicitado y el grupo seleccionado;
  • el estado HTTP y el código de error estructurado;
  • el tiempo total y el tiempo hasta la primera salida efectiva;
  • si quien hizo la llamada la canceló;
  • una descripción depurada de las funciones de la solicitud, como herramientas o entrada de imágenes.

No incluyas la clave de API completa, el prompt, el contenido de la respuesta, el cuerpo de la solicitud sin procesar, el correo electrónico ni la dirección IP en texto plano, salvo que un proceso seguro aprobado lo requiera expresamente.

Una vez ubicada la capa que falla, usa enrutamiento confiable de API de IA para diseñar los respaldos y la guía de streaming para las fallas de eventos y tiempos de espera.

Preguntas frecuentes

¿Un 403 demuestra que un proveedor está caído?

No. Un 403 puede deberse a la política de la cuenta, la clave, el modelo, el grupo, la IP o la función antes de que se seleccione una ruta del proveedor. Revisa primero el registro de la solicitud y el código de error.

¿El 499 es un error estándar del modelo del proveedor?

No. En los registros de solicitudes de Modelflare representa una cancelación downstream observada antes de que se completara la solicitud. Investiga los plazos límite de quien hace la llamada y del proxy antes de tratarlo como una falla del modelo.

¿Se debe reintentar toda respuesta 5xx?

No. Reintenta solo las operaciones que sea seguro repetir, con un límite de intentos y de tiempo, y conserva el primer error. Los problemas deterministas del adaptador o de la solicitud no se resuelven con la repetición.