/v1 est application/problem+json (RFC 9457) et comporte un ensemble de champs fixe :
code, jamais sur detail : code constitue un contrat machine stable, alors que detail est destiné aux utilisateurs et peut évoluer. param est présent lorsque l’erreur est imputable à un paramètre précis de la requête. Indiquez request_id lorsque vous contactez le support.
Codes d’erreur
L’ensemble de 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 situation peut se résoudre d’elle-même ; elle ne prouve pas qu’une écriture n’a eu aucun effet. Relancez les lectures avec un nombre de tentatives et un budget de temps limités, en appliquant un backoff exponentiel avec jitter. Respectez Retry-After lorsqu’il est présent, y compris sur une réponse 409 ou 429 pour laquelle une nouvelle tentative est possible.
Pour les mutations, suivez le contrat d’idempotence et de reprise documenté de l’opération. Conservez la clé d’origine et la requête d’origine lorsque cela est pris en charge. Ne générez 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 abouti. Un en-tête Idempotency-Key n’offre aucune protection sur une opération qui ne le prend pas en charge.