Les erreurs reviennent avec un code de statut HTTP standard et, presque toujours, un petit corps JSON expliquant ce qui a mal tourné.

Le corps de l’erreur

Les échecs renvoient un objet JSON à un seul champ :

{ "error": "client not found" }

Il n’y a pas de champ code, message, ou details. La chaîne error lisible par un humain est tout ce que vous obtenez, donc basez-vous sur le code de statut HTTP, pas sur le texte.

Deux exceptions à cette forme :

• 429 Too Many Requests porte un champ supplémentaire : { "error": "rate_limited", "message": "Too many requests; please slow down." }. Sur les points d’entrée d’identifiants (connexion, inscription, rafraîchissement, acceptation d’invitation et échange de changement de mot de passe), le corps est à la place le générique { "error": "too many attempts; please try again later" }, sans en-têtes x-ratelimit-*. Voir Limites de débit.
• 401 Unauthorized renvoyé par le middleware d’authentification (un jeton bearer manquant ou invalide) n’a aucun corps du tout - seulement le code de statut.

Codes de statut

Validation : 400 contre 422

Les deux signifient que votre entrée a été rejetée, et la frontière entre eux est fine :

• 400 est renvoyé quand la charge utile ne peut pas être analysée ou échoue à la validation de base des champs (un champ requis manquant, une énumération non analysable, un mot de passe trop court).
• 422 est renvoyé quand la charge utile est analysée proprement mais viole une règle du domaine (un montant négatif, un jour hors de la période de la feuille de temps, une affectation qui ne correspond pas).

Traitez les deux cas de la même façon : corrigez la requête avant de la renvoyer.

Conflits de machine à états : 409

Plusieurs ressources sont des machines à états, et agir dans le désordre produit 409. Exemples :

• Modifier ou supprimer une feuille de temps qui n’est plus draft.
• Soumettre une feuille de temps déjà submitted ou validated.
• Annuler un frais déjà paid.
• Créer un client quand le quota du plan est atteint.
• S’inscrire avec un e-mail qui existe déjà.

Quand vous obtenez 409, relisez la ressource pour voir son état actuel plutôt que de réessayer à l’aveugle.

Un modèle de gestion

send request
  -> 2xx: done
  -> 401: refresh once, retry once; on second 401, log out
  -> 400 / 422: surface the error text, do not retry
  -> 403 / 404: do not retry (permission or existence)
  -> 409: re-read the resource, reconcile, then decide
  -> 429: wait for Retry-After, then retry
  -> 5xx: retry with exponential backoff, cap attempts

Ne réessayez jamais 403 ou 404 ; ils ne changeront pas sans une requête différente ou des identifiants différents.