Guías

Errores, límites y reintentos

Lee las respuestas de error y las cabeceras de límite de velocidad, reintenta de forma segura y diagnostica fallos habituales.

Todas las API de Felo devuelven un cuerpo de error JSON con un código de error estable y un ID de solicitud. Lee primero el estado HTTP, después el código y por último el mensaje.

Sobre de error

Las respuestas de producción actuales usan el estado HTTP como status:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

Campo	Significado
`status`	Código de estado HTTP, repetido en el cuerpo
`code`	Código de error legible por máquina
`message`	Explicación legible por personas
`request_id`	Identificador opaco de esta solicitud; inclúyelo en las solicitudes de soporte

Algunos ejemplos de endpoints antiguos usan status: "error" y una cadena de código distinta. Bifurca según el estado HTTP y code, no según el texto exacto de message.

Códigos habituales

HTTP	Código	Qué significa	Qué hacer
400	Código de validación específico del endpoint	Falta un parámetro o no es válido	Corrige la solicitud; no la reintentes sin cambios
401	`UNAUTHORIZED`	Clave de API ausente, no válida, caducada o revocada	Envía `Authorization: Bearer $FELO_API_KEY`; rota la clave si está revocada
402	`INSUFFICIENT_CREDITS`	No hay suficientes créditos de servicio	Recarga en Facturación de la consola y vuelve a intentarlo
404	Específico del endpoint	Modelo, tarea o ruta desconocidos	Comprueba el ID de modelo o de tarea y la ruta del endpoint
429	`RATE_LIMITED`	Se superó un límite de solicitudes	Espera a `Retry-After` y vuelve a intentarlo
5xx	`CHAT_FAILED`, `*_FAILED`, `SERVICE_UNAVAILABLE`	Fallo del servicio o de un upstream	Reintenta con retroceso exponencial; contacta con soporte si persiste

Las referencias de los endpoints enumeran los códigos específicos de cada uno. Empieza por los errores de la Chat API o por la referencia del endpoint que estés llamando.

Endpoints de generación de modelos

POST /api/v1/images/generations y POST /api/v1/videos/generations devuelven los errores de nivel de endpoint con el sobre de OpenAI en lugar del sobre anterior:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

El ID de solicitud está en el encabezado de respuesta X-Request-Id, no en el cuerpo. Una solicitud rechazada no crea una tarea. Una vez que existe una tarea, la mayoría de los fallos llegan como un estado terminal de la tarea en una respuesta 200 en lugar de como un error HTTP: comprueba si status es failed o interrupted y después lee error.message. Consulta Generación de imágenes y Tareas asíncronas.

ID de solicitud

Los cuerpos de error de Felo incluyen request_id. Regístralo junto con el endpoint, el estado HTTP, el código de error, el ID de modelo y el ID de tarea. Nunca registres la clave de API completa.

La Model API también acepta un encabezado de solicitud X-Request-Id opcional. Cuando envías uno, se devuelve tal cual para diagnóstico, lo que te permite correlacionar tus propios registros con una solicitud. Si no envías ninguno, usa el request_id devuelto.

Límites de solicitudes

/v2/chat es el único endpoint de Felo con límites de solicitudes aplicados y documentados:

Por clave de API, ventana de 1 minuto.
Por usuario, ventana de 1 minuto.
Por usuario, ventana de 1 hora.

Los usuarios con una suscripción de pago de Felo vigente, incluidas las suscripciones empresariales, están exentos y no reciben encabezados X-RateLimit-*. Si no se puede verificar el estado de la suscripción, los límites siguen aplicándose.

Encabezado	Significado
`X-RateLimit-Limit`	Límite de la dimensión más restrictiva actualmente en vigor
`X-RateLimit-Remaining`	Cuota restante mínima entre las tres dimensiones
`X-RateLimit-Reset`	Marca de tiempo Unix en segundos en la que se restablece la ventana actual
`Retry-After`	En un 429, el retraso recomendado en segundos

Los demás endpoints /v2/** no tienen límites de solicitudes aplicados actualmente. Las solicitudes a la Model API pueden seguir limitadas por el proveedor upstream, lo que puede manifestarse como un 429.

No codifiques límites numéricos directamente. Lee los encabezados de cada respuesta.

Política de reintentos

Situación	¿Reintentar?
400, 401, 402, 404	No. Corrige primero la solicitud, la clave o el saldo.
429	Sí, después de `Retry-After` o `X-RateLimit-Reset`.
5xx, tiempos de espera, restablecimientos de conexión	Sí, con retroceso exponencial y jitter.
Conexión de streaming interrumpida a mitad de la respuesta	Reintenta solo si tu aplicación puede tolerar una generación duplicada.

Bucle recomendado:

Reintenta solo solicitudes idempotentes o seguras de repetir.
Usa retroceso exponencial: empieza en torno a 1 segundo, duplícalo y limita el máximo a 30 segundos.
Añade jitter aleatorio para que los clientes no reintenten al unísono.
Detente tras un número reducido de intentos y muestra el error.
En un 429, respeta Retry-After en lugar de tu propio calendario.

Secuencia de depuración

Comprueba que la clave esté presente y no revocada.
Llama a GET /api/v1/models con la misma clave para confirmar la autenticación.
Envía la solicitud válida más pequeña al endpoint de destino.
Añade streaming, herramientas o entradas grandes de uno en uno.
Para trabajo asíncrono, comprueba el estado de la tarea antes de volver a enviarla.