Protocole
Erreurs
La forme unique des erreurs, et ce que votre application fait de chaque statut.
Une erreur est un document application/problem+json qui porte toujours :
| Champ | Sens |
|---|---|
code | stable, à lire par votre code |
detail | une phrase en anglais, pour vos journaux |
requestId | aussi dans l'en-tête X-Request-Id ; donnez-le au support |
errors | ce qui est faux, quand il y a quelque chose à pointer |
errors a une seule forme, dans un 422 comme dans un événement refusé :
{
"code": "invalid_payload",
"detail": "…",
"requestId": "6c0b1e9a-4f1d-4d7e-9a51-1f2b3c4d5e6f",
"errors": [
{ "path": "facts.mirrorableFields", "code": "required", "message": "…" },
{ "path": "color", "code": "unknown_field", "message": "\"color\" is not a field of this request." }
]
}
Les codes d'un champ sont des mots : required, blank, wrong_type, unknown_field,
out_of_range, too_long, too_large, too_many, invalid_value, invalid_url,
must_be_positive, in_the_future…
Le code du document suit le statut : invalid_payload (422), conflict (409), rate_limited
(429), forbidden (403), et ceux d'un 401 sont détaillés dans Signature.
Kult Lab refuse un champ inconnu. Une faute de frappe dans un nom de champ revient avec son
chemin dans errors.
Ce que fait votre application
| Statut | Sens | Votre application |
|---|---|---|
200 | lot lu ; voyez le verdict de chaque événement | marque chaque ligne selon son verdict |
401 | clé ou signature (Signature) | s'arrête et alerte ; ne réessaie jamais la même requête |
403 | mauvaise portée, connexion révoquée | s'arrête |
409 | un autre lot est en cours | réessaie dans une seconde |
422 | l'enveloppe elle-même est mal formée | s'arrête : c'est un bug de code |
429 | budget épuisé | respecte Retry-After |
5xx | notre faute | réessaie avec un délai croissant ; la file d'envoi garde tout |
Un corps qui n'est pas du JSON reçoit un 422.
Le commerçant voit les mêmes refus, en français, dans Journal → Requêtes du module API.