Errori

La colonna che conta e' l'ultima: ritentare. Un programma che ritenta un errore che non passera' mai non si accorge di essere fermo, e continua a sembrare vivo mentre non combina niente.

Forma della risposta

Quando qualcosa va storto la risposta ha sempre un campo detail:

{ "detail": "Autenticazione richiesta" }

Se l'errore riguarda i dati inviati, detail e' un elenco e dice quale campo non va:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "password"],
      "msg": "Field required"
    }
  ]
}

I codici

Codice	Significa	Cosa fare	Ritentare
`200`	Fatto.	—	—
`401`	Token mancante, scaduto o credenziali sbagliate.	Rinnova il token con `/api/auth/refresh`. Se anche il rinnovo da' 401, rifai il login.	Una volta, dopo aver rinnovato
`403`	Sei riconosciuto, ma non puoi fare questa cosa: permessi dell'utente o prodotto non in licenza.	Non e' un problema di codice. Servono permessi diversi o il prodotto in licenza.	No
`404`	L'indirizzo non esiste, oppure il documento chiesto non c'e' in quell'azienda.	Controlla l'indirizzo. Se l'indirizzo e' giusto, sospetta l'azienda scelta al login.	No
`422`	I dati inviati non vanno bene.	Leggi `loc`: dice esattamente quale campo. Correggi e rimanda.	No, non finche' non cambi i dati
`500`	Un guasto dalla nostra parte.	Segnalacelo con l'ora della chiamata e l'indirizzo chiamato.	Una o due volte, poi fermati
`503`	Il servizio momentaneamente non risponde.	Aspetta e riprova, allungando l'attesa a ogni tentativo.	Si', con attesa crescente

La distinzione che conta: 401 e 403 si somigliano e vanno trattati all'opposto.

401 vuol dire «non so chi sei»: si risolve con un token nuovo, e ritentare ha senso. 403 vuol dire «so chi sei e la risposta e' no»: ritentare non servira' mai, perche' non dipende dalla chiamata ma dai permessi o dal contratto.

Quando non ritentare mai

403 — la risposta non cambiera' finche' non cambiano permessi o licenza.
422 — se rimandi gli stessi dati ottieni lo stesso errore.
404 su un documento — ritentare non lo fa comparire; quasi sempre e' l'azienda sbagliata.

Se ritenti, fallo con criterio

Attesa crescente — 1 secondo, poi 2, poi 4, poi 8 — e un tetto massimo di tentativi. Ritentare subito e all'infinito peggiora un servizio gia' in affanno e trasforma un rallentamento di un minuto in un blocco.

Quando ci scrivi.

Servono tre cose: l'ora della chiamata, l'indirizzo chiamato e il codice ricevuto. Con queste si trova la richiesta nei registri in un minuto; senza, si procede a tentoni. Non mandare mai il token: e' come la password.