/v1 è application/problem+json (RFC 9457) con un insieme fisso di campi:
code per la logica condizionale, mai detail: code è un contratto macchina stabile, mentre detail è leggibile da un essere umano e può cambiare. param è presente quando l’errore è attribuibile a uno specifico parametro della richiesta. Includere request_id quando si contatta il supporto.
Codici di errore
L’insieme dei codici è chiuso: l’aggiunta di nuovi codici costituisce una modifica del contratto pubblico e viene comunicata tramite il changelog dell’API. Una risposta
retryable: true indica che la condizione potrebbe risolversi, ma non dimostra che una scrittura non abbia avuto effetto. Ripetere le letture con un numero finito di tentativi e un budget di tempo definito, applicando backoff esponenziale e jitter. Rispettare Retry-After quando presente, anche in caso di 409 o 429 ripetibile.
Per le operazioni di modifica, seguire il contratto di idempotenza e di ripristino documentato per l’operazione. Conservare la chiave originale e la richiesta originale, quando supportato. Non generare una nuova chiave dopo un timeout o un 5xx: in tal caso si rischia di ripetere una scrittura già riuscita. Un’intestazione Idempotency-Key non offre alcuna protezione su un’operazione che non la supporta.