Errori e retry
Codici HTTP, formato degli errori e strategie di retry sicure.
Codici
| HTTP | Significato | Azione client |
|---|---|---|
| 400 | Validazione o regola di dominio. | Correggere il payload; non ripetere identico. |
| 401 | Credenziale assente, revocata, scaduta o non valida; tenant sospeso. | Verificare credenziale e ambiente. |
| 403 | Scope/ruolo insufficienti o tipo di chiave sbagliato. | Correggere i permessi. |
| 404 | Risorsa assente/non accessibile nel perimetro. | Verificare id e tenant. |
| 409 | Capacità, stato, versione o riferimenti incompatibili. | Rileggere e risolvere il conflitto. |
| 413 | Corpo troppo grande. | Ridurre il payload; comprimere le foto prima del base64. |
| 5xx / timeout | Esito incerto. | Creazione: stessa idempotencyKey. Transizioni/PATCH: rileggere GET. |
Formato
{
"statusCode": 400, "error": "Bad Request",
"message": [{ "code": "too_small", "path": ["name"], "message": "Too small: expected string to have >=1 characters" }]
}Gli errori di dominio contengono statusCode e message; la validazione restituisce un array di problemi. Non usare il testo inglese come codice stabile. Un proxy può restituire HTML: gestisci anche errori non JSON.
Retry
Imposta timeout e tentativi limitati con attesa crescente e jitter. Non applicare retry automatici indistinti alle POST: l’idempotenza riguarda la creazione delle prenotazioni. Ricreare un prodotto o un periodo dopo un timeout può duplicarlo. Le transizioni possono rispondere 400, anziché 404, se la prenotazione non esiste.