Erreurs

En cas d’échec, l’API renvoie un objet error (jamais data) :

{
  "error": {
    "code": "validation_error",
    "message": "Email is required",
    "field": "email",
    "request_id": "req_abc123"
  }
}

• code est stable et machine-readable — branchez votre logique dessus, pas sur message.
• field n’est présent que pour les erreurs de validation.
• request_id identifie l’appel ; fournissez-le au support.

Codes standards

Code	HTTP	Sens
unauthorized	401	Clé absente ou invalide
forbidden	403	Scope insuffisant
not_found	404	Ressource inexistante dans l’organisation
validation_error	422	Champs invalides
rate_limited	429	Quota de débit dépassé
conflict	409	Conflit d’idempotency ou contrainte unique
internal_error	500	Erreur serveur — fournir le request_id

Gestion côté client

• Traitez 429 avec le header Retry-After (voir Rate limiting).
• Traitez 5xx avec un retry + backoff, idéalement avec une Idempotency-Key sur les POST.
• Loguez le request_id pour faciliter le support.