/v1 est application/problem+json (RFC 9457) et comporte un ensemble de champs fixe :
code, jamais sur detail : code constitue un contrat machine stable, tandis que detail est destiné aux humains et peut changer. param est présent lorsque l’erreur est attribuable à un paramètre précis de la requête. Incluez request_id lorsque vous communiquez avec le soutien technique.
Codes d’erreur
L’ensemble des codes est fermé : tout nouveau code constitue une modification du contrat public et est annoncé dans le journal des modifications de l’API. Une réponse
retryable: true signifie que la condition peut se résorber; elle ne prouve pas qu’une écriture est restée sans effet. Relancez les lectures avec un nombre de tentatives et une durée totale limités, un délai d’attente exponentiel et une composante aléatoire (gigue). Respectez Retry-After lorsqu’il est présent, y compris en cas de 409 ou de 429 pouvant faire l’objet d’une nouvelle tentative.
Pour les mutations, suivez le contrat d’idempotence et de reprise documenté de l’opération. Conservez la clé et la requête d’origine lorsque cela est pris en charge. N’inventez pas de nouvelle clé après un délai d’attente dépassé ou un 5xx : vous risqueriez de répéter une écriture ayant réussi. Un en-tête Idempotency-Key n’offre aucune protection sur une opération qui ne le prend pas en charge.