Erreurs, limites et nouvelles tentatives

Chaque API Felo renvoie un corps d'erreur JSON avec un code d'erreur stable et un ID de requête. Lisez d'abord le statut HTTP, puis le code, puis le message.

Enveloppe d'erreur

Les réponses de production actuelles utilisent le statut HTTP comme status :

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

Certains exemples d'endpoints plus anciens utilisent status: "error" et une chaîne de code différente. Basez votre logique sur le statut HTTP et le code, pas sur le libellé exact de message.

Codes courants

Les références d'endpoint listent les codes propres à cet endpoint. Commencez par les erreurs du Chat API ou par la référence de l'endpoint que vous appelez.

Endpoints de génération par modèle

POST /api/v1/images/generations et POST /api/v1/videos/generations renvoient les erreurs au niveau de l'endpoint dans l'enveloppe OpenAI plutôt que dans l'enveloppe ci-dessus :

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

L'ID de requête se trouve dans l'en-tête de réponse X-Request-Id, et non dans le corps. Une requête rejetée ne crée pas de tâche. Une fois qu'une tâche existe, la plupart des échecs arrivent comme statut terminal de tâche dans une réponse 200 plutôt que comme erreur HTTP : vérifiez status pour failed ou interrupted, puis lisez error.message. Consultez Génération d'images et Tâches asynchrones.

ID de requête

Les corps d'erreur Felo incluent request_id. Journalisez-le avec l'endpoint, le statut HTTP, le code d'erreur, l'ID de modèle et l'ID de tâche. Ne journalisez jamais la clé API complète.

Le Model API accepte aussi un en-tête de requête X-Request-Id facultatif. Lorsque vous en envoyez un, il est renvoyé pour le diagnostic, ce qui vous permet de corréler vos propres logs avec une requête. Si vous n'en envoyez pas, utilisez le request_id renvoyé.

Limites de débit

/v2/chat est le seul endpoint Felo avec des limites de débit appliquées et documentées :

• Par clé API, fenêtre de 1 minute.
• Par utilisateur, fenêtre de 1 minute.
• Par utilisateur, fenêtre de 1 heure.

Les utilisateurs disposant d'un abonnement Felo payant effectif, y compris les abonnements entreprise, en sont exemptés et ne reçoivent aucun en-tête X-RateLimit-*. Si le statut d'abonnement ne peut pas être vérifié, les limites s'appliquent.

Les autres endpoints /v2/** n'ont actuellement aucune limite de débit appliquée. Les requêtes au Model API peuvent toujours être limitées par le fournisseur upstream, ce qui peut se manifester par un 429.

Ne codez pas les limites numériques en dur. Lisez les en-têtes de chaque réponse.

Politique de nouvelle tentative

Boucle recommandée :

1. Ne réessayez que les requêtes idempotentes ou sûres à répéter.
2. Utilisez un backoff exponentiel : commencez autour de 1 seconde, doublez à chaque fois, plafonnez à 30 secondes.
3. Ajoutez un jitter aléatoire pour que les clients ne réessaient pas au même instant.
4. Arrêtez-vous après un petit nombre de tentatives et remontez l'erreur.
5. Sur un 429, respectez Retry-After plutôt que votre propre calendrier.

Séquence de débogage

1. Vérifiez que la clé est présente et non révoquée.
2. Appelez GET /api/v1/models avec la même clé pour confirmer l'authentification.
3. Envoyez la plus petite requête valide à l'endpoint cible.
4. Ajoutez le streaming, les outils ou des entrées volumineuses un élément à la fois.
5. Pour un travail asynchrone, vérifiez l'état de la tâche avant de soumettre à nouveau.

Voir aussi

• Authentification
• Canaux et routage fournisseur
• Tâches asynchrones
• Dépannage