Gestion des erreurs

Format de réponse d'erreur

Toutes les erreurs API suivent une structure JSON cohérente :

{
  "statusCode": 422,
  "message": "La validation a échoué",
  "error": "Unprocessable Entity",
  "details": [
    {
      "field": "price",
      "message": "Le prix doit être un nombre positif"
    },
    {
      "field": "sku",
      "message": "Le SKU existe déjà"
    }
  ]
}

Codes de statut HTTP

Erreurs client (4xx)

Erreurs serveur (5xx)

Erreurs courantes et solutions

401 — Clé API invalide

{
  "statusCode": 401,
  "message": "Clé API invalide",
  "error": "Unauthorized"
}

Solutions :

• Vérifiez que la clé API est correcte et n'a pas été révoquée
• Vérifiez que le nom de l'en-tête est X-API-Key (sensible à la casse)
• Assurez-vous que la clé est pour le bon environnement (live vs test)

403 — Scope insuffisant

{
  "statusCode": 403,
  "message": "La clé API n'a pas le scope requis : products:write",
  "error": "Forbidden"
}

Solution : Générez une nouvelle clé API avec les scopes requis depuis Paramètres → Intégrations.

422 — Erreurs de validation

{
  "statusCode": 422,
  "message": "La validation a échoué",
  "error": "Unprocessable Entity",
  "details": [
    { "field": "name", "message": "Le nom est obligatoire" },
    { "field": "price", "message": "Le prix doit être >= 0" }
  ]
}

Solution : Vérifiez le tableau details pour les erreurs spécifiques par champ et corrigez votre corps de requête.

429 — Limite de débit dépassée

Solution : Attendez la durée indiquée par l'en-tête Retry-After, puis réessayez. Voir Limites de débit pour les bonnes pratiques.

Bonnes pratiques de gestion des erreurs

• Vérifiez toujours le code de statut avant d'analyser le corps de la réponse
• Journalisez les réponses d'erreur avec l'URL de la requête et les en-têtes (en excluant les clés API) pour le débogage
• Implémentez une logique de nouvelle tentative pour les erreurs 429 et 5xx avec un backoff exponentiel
• N'exposez jamais les erreurs API brutes aux utilisateurs finaux — mappez-les vers des messages conviviaux
• Utilisez le tableau details pour les erreurs 422 pour afficher des messages de validation par champ