Errori
La forma
Ogni fallimento restituisce application/problem+json, secondo la
RFC 9457. Lo stato HTTP ti dice
la classe del problema; code ti dice esattamente quale.
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
X-Request-Id: req_4b81f0c9
{
"type": "https://skautik.com/docs/developers/errors#validation_failed",
"title": "Validation failed",
"status": 422,
"code": "validation_failed",
"detail": "One or more fields could not be accepted.",
"request_id": "req_4b81f0c9",
"errors": [
{
"field": "price",
"code": "out_of_range",
"detail": "Must be a positive integer in minor units."
},
{
"field": "address.country",
"code": "unknown_value",
"detail": "Expected an ISO 3166-1 alpha-2 code."
}
]
}L'array errors compare soltanto su un 422. Indica tutti i problemi in una volta invece
del primo, così un modulo può essere corretto in una sola passata anziché un campo per
ogni andata e ritorno.
Ramifica su code e non sulla prosa di title o detail. Il codice è
stabile; la prosa è scritta per una persona e può essere riformulata.
Codici
| Codice | Stato | Significato | Cosa fare |
|---|---|---|---|
authentication_required | 401 | Nessuna chiave, o una chiave non valida. | Correggi l'intestazione o la chiave. Riprovare senza modifiche non riuscirà mai. |
permission_denied | 403 | Chiave valida, ma l'ambito o la proprietà della scheda lo vietano. | Usa una chiave con ambito di scrittura, oppure smetti di modificare una scheda che non hai pubblicato. |
not_found | 404 | Risorsa inesistente, o nessuna che la tua chiave possa vedere. | Trattalo come un'assenza. Non è un guasto passeggero. |
conflict | 409 | Una Idempotency-Key è stata riutilizzata con un corpo diverso. | Genera una chiave nuova per una creazione davvero nuova. |
managed_by_import | 409 | La scheda appartiene a una fonte di importazione, che fa fede su di essa. | Modificala nel sistema che alimenta l'importazione, non qui. |
precondition_failed | 412 | L'If-Match non corrispondeva all'ETag attuale. | Rileggi, riapplica la tua modifica, riprova una volta. |
payload_too_large | 413 | Il caricamento supera il limite del suo endpoint. | Ridimensiona prima di caricare. Non riprovare con gli stessi byte. |
unsupported_media_type | 415 | Il Content-Type manca o non è accettato. | Invia application/json, oppure multipart/form-data per i caricamenti. |
validation_failed | 422 | Il corpo è stato analizzato ma un campo non è accettabile. | Leggi l'array errors; ogni voce indica un campo e il motivo del fallimento. |
rate_limited | 429 | Limite di picco superato. Il volume mensile non rifiuta. | Aspetta il Retry-After, poi riprova con uno scarto casuale. |
internal_error | 500 | Un guasto dalla nostra parte. | Riprova con attesa esponenziale. Cita il request_id se persiste. |
service_unavailable | 503 | Temporaneamente impossibilitati a servire, di solito durante un rilascio. | Riprova con attesa. Di solito si risolve in pochi secondi. |
Cosa riprovare
La regola è semplice, e sbagliarla è il modo più comune in cui un'integrazione trasforma un piccolo disservizio in uno grande.
- 4xx: non riprovare, a meno che non sia un 429. La richiesta è sbagliata, e ripeterla resterà sbagliata. Le eccezioni sono il 429 e il 412, che si riprova una volta dopo aver riletto.
- 5xx: riprova con attesa esponenziale e scarto casuale, entro un budget limitato. Mai in un ciclo stretto: un servizio in difficoltà si riprende tanto più lentamente quanto più lo spingi.
- I timeout sono ambigui. Una richiesta andata in timeout potrebbe comunque essere stata applicata. È esattamente a questo che servono le chiavi di idempotenza sulle scritture.
Segnalare un problema
Cita il request_id quando scrivi a
support@skautik.com. Con quello possiamo trovare la richiesta
esatta; senza, la prima cosa che chiederemo sarà una riproduzione. Registra
l'intestazione a ogni chiamata fallita, così ce l'hai quando serve.