Separare stato, tipo e occorrenza
RFC 9457 definisce application/problem+json. Usare un tipo stabile e un dettaglio comprensibile; il client non dovrebbe interpretare frasi tradotte per decidere. L’eventuale campo status deve corrispondere allo stato HTTP effettivo.
| Stato | Significato HTTP | Gestione da valutare |
|---|---|---|
| 400 | Richiesta errata | Correggere prima di riprovare. |
| 401 | Credenziali valide assenti | Verificare credenziali e meccanismo previsto. |
| 403 | Richiesta compresa ma rifiutata | Verificare diritti; ripetere non li concede. |
| 503 | Servizio temporaneamente indisponibile | Attesa e tentativi limitati se consentiti. |
Prevedere i percorsi di errore
- Documentare codici, formati e gestione attesa. Provare risposte vuote, contenuti non JSON del gateway, disconnessioni e timeout.
- Validare input e autorizzazioni sul server. Gestire errori previsti senza nascondere anomalie sconosciute; non mascherare un fallimento funzionale come successo.
- Restituire un identificativo di correlazione per il supporto. Escludere stack trace, query interne, password e token dalle risposte pubbliche.
Riprovare solo quando appropriato
5xx non autorizza tentativi illimitati. Combinare contratto, stato dell’operazione, idempotenza e scadenza. Segnalare difetti con una riproduzione minima ripulita; dopo la correzione provare il caso originale e i dinieghi di accesso vicini.
Fonti primarie
Gli errori API dovrebbero guidare l'azione senza divulgazioni.
Lo stato HTTP fornisce una categoria iniziale, ma un client potrebbe aver bisogno di un tipo stabile e di dettagli utili. RFC 9457 descrive una struttura di problema comune; non giustifica l'esposizione di tracce interne o dati sensibili.
- Separare il rifiuto permanente, l'input correggibile e l'errore temporaneo.
- Documentare il tipo, lo stato e la possibile azione del client per ogni errore importante.
- Verificare che le risposte non contengano segreti o payload completi non necessari.
Fonte primaria: IETF RFC 9457 — Problem Details for HTTP APIs. Metodo correlato: consultare la guida pratica.
Tentativi API: contare l’intero budget di tempo
Definire limite delle chiamate e scadenza globale.
Caso didattico fittizio: i numeri non rappresentano CIE o clienti.
Modello fittizio: quattro chiamate fino a 250 ms e attese di 100, 200, 400 ms. Esclusi jitter, connessione, code e verifica locale.
- Tentativi totali
- 41 + 3
- Attese accumulate (ms)
- 700100 + 200 + 400
- Budget modellato (ms)
- 17004 × 250 + 700
| Passo | Chiamata massima (ms) | Attesa successiva (ms) |
|---|---|---|
| Tentativo 1 | 250 | 100 |
| Tentativo 2 | 250 | 200 |
| Tentativo 3 | 250 | 400 |
| Tentativo 4 | 250 | 0 |
| Totale | 1000 | 700 |
- Tempo delle chiamate1000
- Attese accumulate700
- Scadenza globale (ms)1500
Controlli prima di concludere
- 1.000 + 700 = 1.700 ms supera la scadenza di 1.500 ms.
- Propagare la scadenza globale ed evitare effetti duplicati; timeout non significa annullamento remoto.
Provare un budget di tentativi
n × T + W × (2^(n−1) − 1)
Metodo correlato: consultare la guida pratica.
Errori API: tipi, stati e prove
Le note dettagliate di questa edizione sono disponibili in inglese.
Handle an error without parsing its sentence
An API client may receive a translated title, missing member or unfamiliar extension. Preserve decisions based on the documented type and HTTP status, then connect a safe action to the context.
- Compare received status and JSON status without silently replacing either.
- Test absent type, string status instead of a number, and an unknown extension.
- Separate person-facing text, business code and occurrence reference.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5