Erreurs

L'enveloppe d'erreur

Chaque erreur — validation, authentification, limite de débit ou serveur — revient dans une forme cohérente unique. Branchez sur le code lisible par machine et présentez message aux humains :

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body is invalid",
    "details": [ /* optionnel, structuré — voir ci-dessous */ ]
  }
}

Le statut HTTP conserve son sens (401 non authentifié, 403 interdit, 404 non trouvé, 422 non traitable, 429 limité en débit, 5xx erreur serveur), mais code est la valeur stable sur laquelle brancher — les messages peuvent être reformulés. Voir la référence des codes d'erreur pour la liste complète.

Détails de validation

Un échec de validation 422 inclut un tableau details. Chaque entrée est normalisée en path, code et message, afin que vous puissiez rattacher les échecs au champ fautif quelle que soit la version du validateur :

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body is invalid",
    "details": [
      { "path": "name", "code": "too_small", "message": "String must contain at least 1 character(s)" },
      { "path": "attributes.netWeight", "code": "invalid_type", "message": "Expected number, received string" }
    ]
  }
}

Identifiants de requête

Chaque réponse porte un en-tête X-Request-ID. Journalisez-le et incluez-le lorsque vous contactez le support — il nous permet de tracer une requête unique de bout en bout à travers la plateforme.