API Reference / Errori e envelope

Errori e envelope

L'involucro comune di ogni risposta e il catalogo completo dei codici di errore: struttura, stati HTTP, dettagli e requestId per la diagnostica.

01L'envelope

Ogni risposta dell'API, di successo o di errore, usa lo stesso involucro JSON. In caso di successo il payload utile sta in data:

json · successo

{ "success": true, "data": … }

In caso di errore, success è false e i dettagli stanno in error:

json · errore

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field \"name\" is required",
    "details": { … },
    "requestId": "a1b2c3d4"
  }
}

02Struttura dell'errore

L'oggetto error ha sempre code e message; details e requestId compaiono solo quando disponibili.

Campo	Tipo		Descrizione
code	string	sempre	Codice macchina stabile (vedi tabella sotto). Usalo per il branching, non il messaggio.
message	string	sempre	Descrizione leggibile, pensata per il debug più che per l'utente finale.
details	object	talvolta	Contesto aggiuntivo (es. campo non valido, campi non scrivibili). Presente quando l'errore lo fornisce.
requestId	string	talvolta	Identificativo della richiesta per correlare l'errore ai log del server.

Nota

Basa la logica applicativa su error.code e sullo stato HTTP, mai sul testo di message: il messaggio può cambiare, il codice no.

03Codici e stati

I codici che l'API può restituire, con lo stato HTTP e la causa tipica.

Stato	Codice	Quando
400	`BAD_REQUEST`	Richiesta malformata o parametro non accettabile.
400	`INVALID_JSON`	Body JSON non parsabile.
401	`UNAUTHORIZED`	Autenticazione fallita: token assente/scaduto/revocato, credenziali di login errate (risposta identica per utente inesistente) o refresh token non valido. Distingui i casi dall'endpoint chiamato, non dal codice.
403	`FORBIDDEN`	Autenticato ma senza permesso per modulo/azione/campo, o fuori scope in scrittura.
403	`PASSWORD_CHANGE_REQUIRED`	Cambio password obbligatorio pendente: solo le rotte di cambio password rispondono.
404	`NOT_FOUND`	Risorsa inesistente o fuori dal tuo scope di visibilità (stessa risposta, anti information-disclosure).
413	`PAYLOAD_TOO_LARGE`	Body oltre il limite configurato.
422	`VALIDATION_ERROR`	Body o query non validi; il messaggio indica il campo.
429	`TOO_MANY_REQUESTS`	Rate limit di autenticazione o account temporaneamente bloccato.
500	`INTERNAL_SERVER_ERROR`	Errore inatteso lato server: il `requestId` aiuta a rintracciarlo nei log.
501	`NOT_IMPLEMENTED`	Funzionalità non ancora disponibile.

04Dettagli utili

Alcuni errori arricchiscono details per farti reagire con precisione:

Validazione (422): il message nomina il campo che ha fallito (es. Field "email" is invalid).
Campi non scrivibili (403 FORBIDDEN): quando provi a scrivere un campo non consentito dal ruolo, details elenca i campi negati (deniedFields), così sai quali togliere dal payload.
Permessi: i dinieghi su modulo/azione portano il contesto (module, action, scope richiesto) usato anche per l'audit lato server.

05requestId e diagnostica

Ogni risposta d'errore può includere un requestId. È lo stesso identificativo che il server scrive nei log per quella richiesta: allegalo quando segnali un problema, così l'errore lato client si aggancia esattamente alla traccia lato server. Gli errori 5xx sono sempre loggati con stack; i 4xx come warning.

← PrecedenteAutenticazione Successiva →Paginazione e filtri