/v1 és application/problem+json (RFC 9457) amb un conjunt fix de camps:
code, mai en detail: code és un contracte de màquina estable; detail és llegible per a les persones i pot canviar. param hi és present quan l’error es pot atribuir a un paràmetre concret de la sol·licitud. Inclogueu request_id quan contacteu amb el suport.
Error codes
El conjunt de codis és tancat: els codis nous suposen un canvi en el contracte públic i s’anuncien mitjançant el registre de canvis de l’API. Una resposta
retryable: true indica que la condició pot resoldre’s; no demostra que una escriptura no hagi tingut cap efecte. Reintenteu les lectures amb un nombre finit d’intents i un pressupost de temps limitat, amb retrocés exponencial i jitter. Respecteu Retry-After quan hi sigui present, també en un 409 o 429 reintentable.
Per a les mutacions, seguiu el contracte d’idempotència i recuperació documentat de l’operació. Conserveu la clau i la sol·licitud originals quan sigui compatible. No genereu una clau nova després d’un temps d’espera esgotat o d’un 5xx: podríeu repetir una escriptura que s’ha dut a terme correctament. Una capçalera Idempotency-Key no ofereix cap protecció en una operació que no la admet.