Erreurs

Envoyez toujours Accept: application/json pour recevoir les erreurs en JSON.

Codes de statut et enveloppes

Statut	Quand	Forme du corps
`400`	Erreurs de grant OAuth	`{ "error": "invalid_grant", "error_description": "..." }`
`400`	Contexte d'organisation manquant	`{ "success": false, "error": "organization_required", "message": "..." }`
`401`	Jeton manquant/invalide/révoqué	`{ "success": false, "error": "Unauthenticated", "message": "Invalid token" }`
`403`	Permission ou scope insuffisant	`{ "message": "This action is unauthorized." }`
`404`	Ressource introuvable — ou inaccessible depuis votre organisation	`{ "message": "No query results for model [...]" }`
`422`	Échec de validation	Voir ci-dessous
`429`	Limite de débit dépassée	`{ "message": "Too Many Attempts." }` + en-tête `Retry-After`
`5xx`	Erreur serveur	`{ "message": "Server Error" }`

Erreurs de validation (422)

{
  "message": "The customer id field is required. (and 1 more error)",
  "errors": {
    "customer_id": ["The customer id field is required."],
    "items": ["The items field is required."]
  }
}

errors associe chaque champ invalide à un tableau de messages lisibles.

Conseils de traitement

Les enveloppes ne sont pas uniformes selon les codes de statut (compromis connu, maintenu stable pour la rétrocompatibilité). Analysez défensivement :

Si le corps contient errors sous forme d'objet champ → messages, traitez-le comme une erreur de validation.
Sinon, s'il contient un champ error de type chaîne, traitez error comme un code machine et message comme texte d'affichage.
Sinon, repliez-vous sur message.

Un 404 sur une ressource que vous pensez exister signifie généralement qu'elle appartient à une autre organisation que celle sélectionnée par votre jeton/en-tête — l'API ne distingue volontairement pas « n'existe pas » de « pas à vous ».