Codes d'erreur & réponses

Enveloppe de réponse

Chaque réponse de style action suit une forme cohérente. En cas de succès :

{ "success": true, "data": { /* … */ } }

En cas d’échec :

{
  "success": false,
  "error": "Variant is required",        // lisible par l'homme, pour vos logs
  "errorCode": "VARIANT_REQUIRED",        // stable, se brancher sur ceci
  "fieldErrors": [                          // présent pour la validation d'entrée
    { "field": "variantId", "code": "VARIANT_REQUIRED" }
  ]
}

Les réponses peuvent aussi porter businessRuleWarnings (quand une règle a alerté mais autorisé l’action) et approvalRequested (quand une politique d’approbation a intercepté une validation). Toujours se brancher sur errorCode, pas sur le texte error — le texte est pour les logs et peut changer ou être localisé ; le code est stable.

Mappage du statut HTTP

Les erreurs sont catégorisées et la catégorie détermine le statut HTTP (avec quelques remplacements par code) :

Catégorie	HTTP	Exemples
Validation	`400`	`VALIDATION_ERROR`, `MISSING_REQUIRED_FIELD`, `VARIANT_REQUIRED`
Auth	`401`	`UNAUTHORIZED`, `FORBIDDEN`
Non trouvé	`404`	`RECORD_NOT_FOUND`, `PLAN_NOT_FOUND`
Métier	`422`	`BUSINESS_RULE_VIOLATION`, `INSUFFICIENT_STOCK`
Limite de débit	`429`	`RATE_LIMIT_EXCEEDED`
Externe	`502`	`EXTERNAL_SERVICE_ERROR`, `EXTERNAL_SERVICE_TIMEOUT`
Base de données / Configuration / Inconnu	`500`	`DATABASE_ERROR`, `UNKNOWN_ERROR`

Un remplacement notable : PLAN_ALREADY_VALIDATED retourne 409 Conflict plutôt que 422.

Codes d’erreur courants

Code	Signification	Que faire
`UNAUTHORIZED`	Token manquant, invalide, révoqué ou expiré	Ré-authentifiez-vous / émettez un nouveau token
`FORBIDDEN`	Token manque la permission requise	Accordez la permission sur le token ; ne réessayez pas tel quel
`VALIDATION_ERROR`	L’entrée a échoué la validation	Inspectez `fieldErrors` ; corrigez la charge utile
`RECORD_NOT_FOUND` / `PLAN_NOT_FOUND`	La ressource n’existe pas (ou pas dans votre org)	Vérifiez l’id ; ne réessayez pas
`BUSINESS_RULE_VIOLATION`	Une règle métier a bloqué l’action	Lisez le message / avertissements ; ajustez la requête
`PLAN_ALREADY_VALIDATED`	Le plan est au-delà de l’état sur lequel vous agissez	Re-récupérez le statut actuel du plan
`RATE_LIMIT_EXCEEDED`	Trop de requêtes (si appliqué en amont)	Retournez-vous et réessayez
`DATABASE_ERROR` / `UNKNOWN_ERROR`	Erreur serveur inattendue	Réessayez une fois ; escaladez si persistant

Il y a plus d’une centaine de codes spécifiques (validation, opérations plan/article, téléchargement de fichier, tokens API, …). Chaque endpoint documente ceux qu’il peut retourner dans l’onglet Référence API.

Messages localisés

Les codes d’erreur sont découplés du texte d’affichage pour que les messages puissent être affichés dans la langue de l’utilisateur. Dans l’application web, les codes sont traduits en anglais ou en français ; les intégrateurs doivent se fier au code et rendre leur propre message si nécessaire.

​Enveloppe de réponse

​Mappage du statut HTTP

​Codes d’erreur courants

​Messages localisés

Enveloppe de réponse

Mappage du statut HTTP

Codes d’erreur courants

Messages localisés