Erreurs
Les codes d'état que l'API rend, et ce que porte le corps d'un refus.
Décidez d'après le code d'état. Le corps d'un refus explique pourquoi, pour un humain : montrez-le ou journalisez-le, ne l'analysez pas (il est rédigé dans la langue de l'utilisateur, et sa formulation peut changer).
Les codes
| Code | Ce qu'il dit | Que faire |
|---|---|---|
200 |
Succès. | — |
400 |
Requête refusée : le corps ne se lit pas, ou une valeur est refusée. | Corriger la requête d'après le message. |
401 |
Non authentifié : jeton ou clé API absent, invalide ou expiré. | Demander un nouveau jeton. |
403 |
Interdit : l'utilisateur n'a pas le droit nécessaire, ou le module est fermé à son organisation. | Ne pas réessayer tel quel. |
404 |
Introuvable, ou invisible pour cet utilisateur. | — |
409 |
Conflit avec l'état de la fiche : déjà envoyée, ressemble à une fiche existante… | Relire la fiche, puis décider. |
413 |
Corps trop volumineux. | Réduire l'envoi. |
422 |
Refusé par une règle de la fiche. | Corriger d'après le message. |
429 |
Trop de requêtes. | Attendre, puis réessayer — voir Limites de débit. |
500 |
Erreur du serveur. | Réessayer plus tard ; si elle persiste, contacter l'assistance avec l'heure de l'appel. |
502, 503 |
Un service tiers, ou l'API, est momentanément indisponible. | Réessayer plus tard. |
Le corps d'un refus
Le plus souvent, c'est le message du refus, une chaîne JSON :
"Le corps de la requête doit contenir les propriétés à modifier"Un refus sans message — une requête que l'API n'a pas pu lire, une fiche introuvable sur certaines routes — rend un objet
ProblemDetails (RFC 9457) :
{ "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "title": "Not Found", "status": 404 }La référence dit, pour chaque route, les refus qu'elle déclare et leur forme.
Ce qu'il faut savoir
- Une erreur de création complète (un parcours, un email) peut survenir après un premier enregistrement : le message le dit (« enregistré en brouillon, mais… »). Ne recréez pas : voir Rejouer une requête sans doublon.
GET …/{id}rend200etnullpour un identifiant qui ne désigne aucune fiche et pour une fiche que l'utilisateur n'a pas le droit de voir. C'est une mesure de sécurité : la réponse ne dit jamais si une fiche existe, et un identifiant ne se devine pas d'une organisation à l'autre. Testez le corps autant que le code.