Gestione errori

Le API GipoNext utilizzano codici di stato HTTP standard per comunicare l'esito di ogni richiesta. Questa pagina descrive i codici più comuni, il formato del body di errore e le strategie per gestire correttamente ogni situazione nel tuo codice.

Codici di stato HTTP

Risposte di successo

Codice	Significato	Quando lo ricevi
200 OK	Richiesta completata con successo	Lettura, aggiornamento
201 Created	Risorsa creata con successo	Creazione di una nuova risorsa
204 No Content	Operazione completata, nessun body	Eliminazione, operazioni senza risposta

Errori del client

Codice	Significato	Cosa fare
400 Bad Request	Richiesta malformata o parametri non validi	Controlla il body della risposta per i dettagli. Verifica campi obbligatori, tipi e formati.
401 Unauthorized	Token mancante, scaduto o non valido	Rinnova l'access token con il refresh token. Se anche il refresh token è scaduto, avvia un nuovo login. Vedi Flussi OAuth e token.
403 Forbidden	Token valido ma permessi insufficienti	L'utente non ha i permessi per questa operazione, oppure manca lo scope OAuth richiesto. Verifica scope e ruolo utente.
404 Not Found	Risorsa non trovata	L'ID specificato non esiste o non è accessibile per il tenant corrente. Verifica il tenantId e l'ID della risorsa.
409 Conflict	Conflitto con lo stato corrente della risorsa	Un'altra operazione ha modificato la risorsa nel frattempo. Rileggi la risorsa e riprova.
422 Unprocessable Entity	Dati sintatticamente corretti ma semanticamente non validi	Il body è JSON valido ma i valori non superano le regole di business. Controlla il dettaglio errore nella risposta.
429 Too Many Requests	Limite di traffico superato	Attendi il tempo indicato nell'header Retry-After e riprova. Vedi Rate limiting.

Errori del server

Codice	Significato	Cosa fare
500 Internal Server Error	Errore imprevisto lato server	Non dipende dal tuo codice. Riprova dopo qualche secondo. Se persiste, contatta il supporto.
502 Bad Gateway / 503 Service Unavailable	Servizio temporaneamente non disponibile	Riprova con backoff esponenziale. Il servizio dovrebbe tornare disponibile in breve.

Formato del body di errore

Quando una richiesta fallisce, il body della risposta è in formato JSON e contiene informazioni utili per capire la causa.

{
  "message": "Descrizione leggibile dell'errore",
  "errors": {
    "NomeCampo": [
      "Dettaglio specifico sulla validazione fallita"
    ]
  }
}

💡 Nota

Non tutti gli errori includono il campo errors. I campi presenti dipendono dal tipo di errore. Il campo message è sempre presente nelle risposte di errore con body.

Strategia di gestione errori

Errori recuperabili (riprova automaticamente)

• 401: rinnova il token e riprova la richiesta originale.
• 429: attendi Retry-After secondi e riprova.
• 5xx: riprova con backoff esponenziale (es. 1s, 2s, 4s) fino a un massimo di 3 tentativi.

Errori non recuperabili (correggi la richiesta)

• 400: i parametri sono sbagliati. Leggi il body per capire quale campo ha fallito la validazione.
• 403: l'utente non ha i permessi. Verifica lo scope OAuth e il ruolo dell'utente nel tenant.
• 404: la risorsa non esiste. Verifica tenantId e ID risorsa.
• 422: i dati non rispettano le regole di business. Leggi il body e correggi i valori.

Checklist di troubleshooting

Quando una chiamata fallisce, segui questa sequenza:

1. Controlla il codice HTTP — è la prima informazione utile per capire la categoria del problema.
2. Leggi il body della risposta — il campo message e, se presente, errors ti dicono cosa è andato storto.
3. Verifica il token — se ricevi 401, il token potrebbe essere scaduto. Se ricevi 403, potrebbe mancare uno scope.
4. Verifica il tenantId — se ricevi 404 su una risorsa che sai esistere, potresti star usando il tenantId sbagliato.
5. Controlla i rate limit — se ricevi 429, stai inviando troppe richieste. Vedi Rate limiting.
6. Riprova (se opportuno) — per 401 (dopo refresh), 429 (dopo attesa) e 5xx (dopo backoff).
7. Contatta il supporto — se il problema persiste dopo i controlli, scrivi al supporto specificando endpoint, codice HTTP, body di errore e timestamp.

Prossimi passi

• Rate limiting — gestione specifica del codice 429
• Flussi OAuth e token — rinnovo token e gestione della scadenza
• Entità e operazioni — scope richiesti per ogni risorsa