Gestion des erreurs

L'API The Trade Hub utilise les codes de statut HTTP standard pour indiquer le succès ou l'échec d'une requête. Les codes dans la plage 2xx indiquent un succès, les codes 4xx une erreur côté client, et les codes 5xx une erreur côté serveur.

Format des réponses d'erreur

Toutes les erreurs retournent un corps JSON avec un champ detail décrivant le problème :

{
  "detail": "Description de l'erreur"
}

Pour les erreurs de validation (422), le format inclut des détails supplémentaires :

{
  "detail": [
    {
      "loc": ["body", "content"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Codes d'erreur

401 Unauthorized

Clé API invalide ou manquante. Vérifiez que l'en-tête X-API-Key est présent et contient une clé valide.

{
  "detail": "Clé API invalide ou manquante"
}

Causes courantes :

• En-tête X-API-Key absent de la requête
• Clé API expirée ou révoquée
• Clé copiée avec des espaces ou caractères supplémentaires
• Clé API désactivée par un administrateur de l'organisation

Résolution :

• Vérifiez que l'en-tête est correctement orthographié (X-API-Key, pas X-Api-Key)
• Vérifiez que la clé est active dans le tableau de bord développeur
• Regénérez la clé si nécessaire

402 Payment Required

Solde de crédits insuffisant ou plafond de dépenses atteint. Votre organisation n'a plus de crédits ou a atteint son plafond de dépenses mensuel.

{
  "detail": "insufficient balance"
}

Causes courantes :

• Solde de crédits prépayés épuisé (mode balance)
• Plafond de dépenses mensuel atteint (mode invoice)

Headers additionnels :

• X-Balance-Cents : solde actuel en centimes (mode balance)
• X-Spending-Limit / X-Spending-Current : plafond et dépense courante (mode invoice)

Résolution :

• Rechargez votre solde de crédits depuis le tableau de bord billing
• Ajustez votre plafond de dépenses si nécessaire
• Activez la recharge automatique pour éviter les interruptions

403 Forbidden

Permissions insuffisantes. Votre clé API n'a pas les droits nécessaires pour cette opération.

{
  "detail": "Permissions insuffisantes pour cette opération"
}

Causes courantes :

• Tentative d'accès à une ressource d'une autre organisation
• Clé API avec des permissions restreintes
• Scope de la clé API insuffisant pour cette ressource

Résolution :

• Vérifiez que la ressource appartient à votre organisation
• Contactez l'administrateur de votre organisation pour ajuster les permissions

404 Not Found

Ressource introuvable. L'identifiant spécifié ne correspond à aucune ressource existante.

{
  "detail": "Job non trouvé"
}

Causes courantes :

• Identifiant de job ou de lot incorrect
• Ressource supprimée
• Identifiant d'une autre organisation

Résolution :

• Vérifiez l'identifiant dans votre requête
• Utilisez l'endpoint historique pour retrouver la bonne ressource

422 Unprocessable Entity

Erreur de validation. Le corps de la requête ne respecte pas le format attendu.

{
  "detail": [
    {
      "loc": ["body", "content"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Causes courantes :

• Champ obligatoire manquant (content)
• Type de données incorrect (chaîne au lieu d'un tableau)
• Valeur hors des limites acceptées
• Format JSON invalide dans le corps de la requête

Résolution :

• Consultez la documentation de l'endpoint pour les paramètres requis
• Validez votre JSON avant l'envoi
• Vérifiez les types de données de chaque champ

429 Too Many Requests

Limite de débit atteinte. Vous avez envoyé trop de requêtes dans la fenêtre temporelle.

{
  "detail": "Limite de débit atteinte. Réessayez dans 12 secondes."
}

Résolution :

• Attendez la durée indiquée dans l'en-tête Retry-After
• Implémentez un backoff exponentiel
• Utilisez la classement par lot pour réduire le nombre de requêtes

500 Internal Server Error

Erreur interne du serveur. Une erreur inattendue s'est produite côté serveur.

{
  "detail": "Erreur interne du serveur"
}

Résolution :

• Réessayez la requête après quelques secondes
• Si l'erreur persiste, contactez le support avec l'identifiant de requête
• Vérifiez la page de statut pour des incidents en cours

503 Service Unavailable

Service temporairement indisponible. Le service est en maintenance ou surchargé.

{
  "detail": "Service temporairement indisponible. Réessayez ultérieurement."
}

Résolution :

• Réessayez après quelques minutes
• Vérifiez la page de statut pour des maintenances planifiées
• Implémentez un mécanisme de file d'attente pour les requêtes en échec

Tableau récapitulatif

Gestion recommandée

import httpx

client = httpx.Client(
    base_url="https://api.thetradehub.eu",
    headers={"X-API-Key": "th_live_votre_cle_api"},
)

response = client.post("/v1/classify/jobs", json={
    "content": "Casque audio Bluetooth"
})

match response.status_code:
    case 201:
        job = response.json()
        print(f"Job créé : {job['id']}")
    case 401:
        print("Erreur d'authentification. Vérifiez votre clé API.")
    case 402:
        print("Solde insuffisant. Rechargez vos crédits.")
    case 422:
        errors = response.json()["detail"]
        for error in errors:
            print(f"Validation : {error['loc']} - {error['msg']}")
    case 429:
        retry_after = int(response.headers.get("Retry-After", 10))
        print(f"Rate limited. Réessayez dans {retry_after}s.")
    case code if code >= 500:
        print(f"Erreur serveur ({code}). Réessayez ultérieurement.")
    case _:
        print(f"Erreur inattendue : {response.status_code}")

const response = await fetch("https://api.thetradehub.eu/v1/classify/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": "th_live_votre_cle_api",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ content: "Casque audio Bluetooth" }),
});

switch (response.status) {
  case 201: {
    const job = await response.json();
    console.log(`Job créé : ${job.id}`);
    break;
  }
  case 401:
    console.error("Erreur d'authentification. Vérifiez votre clé API.");
    break;
  case 402:
    console.error("Solde insuffisant. Rechargez vos crédits.");
    break;
  case 422: {
    const { detail } = await response.json();
    for (const error of detail) {
      console.error(`Validation : ${error.loc.join(".")} - ${error.msg}`);
    }
    break;
  }
  case 429: {
    const retryAfter = response.headers.get("Retry-After") || "10";
    console.warn(`Rate limited. Réessayez dans ${retryAfter}s.`);
    break;
  }
  default:
    if (response.status >= 500) {
      console.error(`Erreur serveur (${response.status}). Réessayez ultérieurement.`);
    } else {
      console.error(`Erreur inattendue : ${response.status}`);
    }
}