Format et codes d’erreur de l’API

Chaque réponse d’erreur de l’API a le même format. Votre code doit se fier au code d’erreur du champ error, pas au texte de message – le code reste stable, alors que le texte peut changer et est traduit dans la langue du compte.

#Structure d’une réponse d’erreur

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error

Code lisible par machine, par exemple not_found. Pour la plupart des erreurs, il figure aussi dans l’en-tête X-Error-Code – mais fiez-vous au champ du corps.

message

Description lisible par un humain dans la langue du compte : avec une clé API, celle du propriétaire de l’espace de travail ; avec une application connectée, celle de la personne qui l’a connectée. Sans jeton valide – par exemple pour le 401 du contrôle de jeton –, la langue suit Accept-Language, sinon c’est l’anglais. L’en-tête Content-Language indique la langue utilisée.

details

Présent uniquement s’il y a plus à dire. Pour un 422 issu de la validation des saisies, une liste avec field, reason et message pour chaque problème ; pour un 422 issu de la logique métier et toutes les autres erreurs, un objet, par exemple avec reason, retry_after_sec ou une liste issues. En cas de dépassement de taille, il contient field, reason et limit, et pour 413 request_too_large max_bytes et max_kb. Vérifiez donc si details est une liste.

request_id

L’ID de la requête. Il figure aussi dans l’en-tête X-Request-Id. Indiquez-le quand vous contactez le support.

Exceptions : la réponse 429 rate_limited a le champ retry_after_sec au lieu de details ; avec 429 et 403 insufficient_scope, request_id manque dans le corps. Le 401 du contrôle de jeton et le 422 du contrôle de schéma n’ont pas d’en-tête X-Error-Code ; avec le contrôle de schéma, seul le message de premier niveau est traduit, les textes de details restent en anglais. L’en-tête X-Request-Id est toujours présent.

#Les codes les plus importants

#Lire les erreurs de saisie

Avec 422 validation_failed, details liste chaque problème séparément : field est le chemin du champ (avec des barres obliques pour les objets imbriqués, par exemple theme_config/button_style), reason est la règle enfreinte, comme required, minLength, maxLength, enum ou additionalProperties. Avec additionalProperties, le message indique quels champs sont inconnus – souvent une faute de frappe dans le nom du champ.

#Gestion recommandée dans votre code

• 400, 413 et 422 : ne réessayez pas, corrigez plutôt la requête
• 401 invalid_token : récupérez une fois un nouveau jeton et réessayez
• 403 : ne réessayez pas ; vérifiez la portée, l’offre ou qui a le droit de faire cela
• 404 : vérifiez l’ID ; après une suppression, c’est normal
• 409 : rechargez l’état et décidez si l’action est encore nécessaire
• 429 : attendez le temps indiqué par Retry-After, puis réessayez – voir Limites de débit
• 500 et 503 : réessayez quelques fois avec des pauses croissantes