Gestion des erreurs

Format de réponse d’erreur unifié

Toutes les erreurs API renvoient un format JSON unifié :

JSON

{
  "code": 2010,
  "status": "error",
  "message": "You don't have enough credit to create this task",
  "suggestion": "Please purchase more credit",
  "request_id": "req_abc123"
}

Champ	Tapez	Descriptif
code	entier	Code d’erreur
status	chaîne	Résultat de la requête ; `error` lorsque la requête échoue
message	chaîne	Description de l’erreur
suggestion	chaîne	Solution suggérée
request_id	chaîne	Identifiant de demande unique pour le dépannage

Codes d’état HTTP

Code d’état	Signification	Descriptif
200	Succès	La demande a été traitée avec succès
400	Paramètres invalides	Les paramètres requis sont manquants ou mal formés
401	Non authentifié	Le API Key est manquant ou invalide
403	Autorisations insuffisantes	Vous n’avez pas la permission d’accéder à la ressource ou vos crédits sont insuffisants
404	Ressource introuvable	La tâche ou la ressource demandée n’existe pas
429	Trop de demandes	Limite de débit ou limite de concurrence dépassée. Réduisez la fréquence de vos demandes ou réessayez plus tard
500	Erreur de service	Erreur de serveur interne. Réessayez plus tard

Référence du code d’erreur

Code d’erreur	Signification	Manipulation recommandée
1000	API Key invalide	Vérifiez si le API Key est correct ou a été supprimé
1001	Non autorisé	Vérifiez si l’en-tête de la demande inclut `Authorization`
1007	Limite de débit dépassée	Réduisez la fréquence des requêtes et mettez en place de nouvelles tentatives avec attente exponentielle
2000	Limite de concurrence dépassée	Attendez qu’une tâche de la même catégorie se termine avant d’en créer d’autres, ou respectez le délai indiqué par l’en-tête de réponse `Retry-After`. Voir Limites de débit
2002	Paramètre de requête non pris en charge	Vérifiez si les noms et les valeurs des champs du corps de la requête correspondent à la documentation
2003	Fichier d’entrée vide	Confirmez que le fichier téléchargé n’est pas vide et utilise un format valide
2004	Type de fichier non pris en charge	Vérifiez si le format de fichier est dans la liste prise en charge
2008	Violation des règles relatives au contenu	Modifiez le contenu d’entrée pour éviter les mots ou les images interdits
2010	Crédits insuffisants	Recharger des crédits dans la console
2015	Version obsolète	Mise à niveau vers la dernière version de API
2018	Modèle trop complexe	Réduire la complexité ou le nombre de polycomptes du modèle d’entrée

Exemples de gestion des erreurs

import time
import requests

def call_api_with_retry(url, headers, payload=None, max_retries=3):
    for attempt in range(max_retries):
        if payload:
            response = requests.post(url, headers=headers, json=payload)
        else:
            response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            wait = 2 ** attempt
            print(f"Rate limit triggered. Retrying in {wait} seconds...")
            time.sleep(wait)
            continue

        error = response.json()
        raise Exception(
            f"API error [{error['code']}]: {error['message']} "
            f"(suggestion: {error.get('suggestion', 'none')})"
        )

    raise Exception("Maximum retry attempts exhausted")

async function callApiWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return await response.json();
    }

    if (response.status === 429) {
      const wait = 2 ** attempt * 1000;
      console.log(`Rate limit triggered. Retrying in ${wait / 1000} seconds...`);
      await new Promise(resolve => setTimeout(resolve, wait));
      continue;
    }

    const error = await response.json();
    throw new Error(
      `API error [${error.code}]: ${error.message} (suggestion: ${error.suggestion || "none"})`
    );
  }

  throw new Error("Maximum retry attempts exhausted");
}

Recommandations relatives à la stratégie de nouvelle tentative

Pour les erreurs réessayables, telles que 429 limites de débit et 500 erreurs de service, utilisez une stratégie d’attente exponentielle :

Première tentative : attendez 1 seconde
Deuxième tentative : attendez 2 secondes
Troisième tentative : attendez 4 secondes
Maintenez le nombre maximum de tentatives à 5 ou moins

Pour les erreurs non réessayables, telles que 400, 401 et 403, générez directement une exception et corrigez le problème sous-jacent.