Erreurs courantes

Format de réponse d’erreur

Les endpoints de modèles renvoient les erreurs au format JSON :

{
  "error": {
    "message": "Insufficient user quota, remaining: ＄0.000000 (request id: 202610230158421013999388268d9d615)",
    "type": "error",
    "code": "insufficient_user_quota"
  }
}

message est un texte lisible qui se termine par (request id: <id>). Le même ID figure dans l’en-tête X-Oneapi-Request-Id ; indiquez-le lors d’un contact avec le support.
code est le code d’erreur exploitable par programme. Pour certaines erreurs il vaut une chaîne vide ; utilisez alors le code de statut HTTP.
message est traduit selon la langue du compte ou Accept-Language et peut changer : basez votre logique sur le code de statut HTTP et sur code.

Claude Messages (/v1/messages) renvoie plutôt {"type": "error", "error": {"type": "...", "message": "..."}}. Les endpoints de tâches asynchrones (/v1/video/generations, /v1/videos, /suno/*) renvoient {"code", "message", "data"} pour les erreurs survenues après le routage, et ce message ne contient pas le request id.

401 Unauthorized

La clé API est absente, invalide, expirée, désactivée ou à court de quota :

L’en-tête Authorization est absent ou n’est pas au format Bearer sk-....
La clé a été supprimée, désactivée ou a expiré.
Le quota restant de la clé est épuisé.
Une Management Key (rat_...) a été envoyée à un endpoint de modèle ; les appels de modèle exigent une clé API sk-.

Créez une nouvelle clé sur la page API Keys si nécessaire. Le quota et l’expiration des clés sont décrits dans Solde et quotas.

403 Forbidden

Un 403 a deux causes très différentes ; vérifiez d’abord le code de la réponse.

Solde ou quota de clé insuffisant

insufficient_user_quota : le solde du compte ne couvre pas le coût estimé de la requête, ou l’abonnement n’a plus de quota.
pre_consume_token_quota_failed : le quota restant de la clé ne couvre pas le coût estimé.

Rechargez le compte, augmentez le quota de la clé, ou réduisez max_tokens pour que l’estimation tienne dans le quota. Voir Solde et quotas.

Droits insuffisants

Ces erreurs ont généralement un code vide ; le message indique quel contrôle a échoué :

Les restrictions de modèles de la clé n’incluent pas ce modèle (This token has no access to model ...).
Le groupe de la clé n’est pas disponible pour votre compte.
L’IP source n’est pas dans la liste d’autorisation IP de la clé (code access_denied).
Le compte est désactivé.

429 Too Many Requests

La limite de débit a été dépassée. Les limites sont comptées par compte : toutes les clés d’un même compte partagent le quota, donc ajouter des clés n’augmente pas la limite. Les requêtes rejetées ne sont pas facturées.

Réessayez avec un backoff exponentiel et un jitter aléatoire.
Réduisez la concurrence ou étalez les requêtes dans le temps.
Une réponse 429 peut avoir un corps vide ; fiez-vous au code de statut plutôt qu’au message.

Voir Utilisation et facturation pour le fonctionnement des limites de requêtes de modèles et la reprise des 429 amont.

503 Modèle non disponible

code model_not_found avec un message du type « No valid upstream service » : aucun canal ne sert actuellement ce modèle pour votre groupe. Vérifiez l’orthographe de l’ID de modèle et si le modèle est disponible pour votre compte ; réessayer immédiatement la même requête aide rarement.

502 / 503 Erreur amont

Un 502 ou un autre 5xx du fournisseur de modèle est transmis tel quel lorsque toutes les reprises ont échoué.
code get_channel_failed avec « Upstream service is temporarily unavailable » : le compte amont derrière le canal est inutilisable (solde ou identifiants en échec, par exemple). RouteAPI réessaie sur un autre canal lorsque c’est possible, renvoie ce message générique, déclenche une alerte interne et peut désactiver le canal défaillant ; réessayez plus tard.
code client_failfast (503) : la même clé API échoue à un taux élevé pour ce modèle, une courte fenêtre de protection a donc été ouverte pour cette combinaison clé/modèle. La réponse contient Retry-After et X-Client-Failfast: 1 ; attendez avant de réessayer, et corrigez d’abord la cause de l’échec.

Réessayez plus tard si l’erreur est temporaire. Si elle persiste, contactez le support avec le request id.