Skip to content

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 ​

CodiceSignificatoQuando lo ricevi
200 OKRichiesta completata con successoLettura, aggiornamento
201 CreatedRisorsa creata con successoCreazione di una nuova risorsa
204 No ContentOperazione completata, nessun bodyEliminazione, operazioni senza risposta

Errori del client ​

CodiceSignificatoCosa fare
400 Bad RequestRichiesta malformata o parametri non validiControlla il body della risposta per i dettagli. Verifica campi obbligatori, tipi e formati.
401 UnauthorizedToken mancante, scaduto o non validoRinnova l'access token con il refresh token. Se anche il refresh token è scaduto, avvia un nuovo login. Vedi Flussi OAuth e token.
403 ForbiddenToken valido ma permessi insufficientiL'utente non ha i permessi per questa operazione, oppure manca lo scope OAuth richiesto. Verifica scope e ruolo utente.
404 Not FoundRisorsa non trovataL'ID specificato non esiste o non è accessibile per il tenant corrente. Verifica il tenantId e l'ID della risorsa.
409 ConflictConflitto con lo stato corrente della risorsaUn'altra operazione ha modificato la risorsa nel frattempo. Rileggi la risorsa e riprova.
422 Unprocessable EntityDati sintatticamente corretti ma semanticamente non validiIl body è JSON valido ma i valori non superano le regole di business. Controlla il dettaglio errore nella risposta.
429 Too Many RequestsLimite di traffico superatoAttendi il tempo indicato nell'header Retry-After e riprova. Vedi Rate limiting.

Errori del server ​

CodiceSignificatoCosa fare
500 Internal Server ErrorErrore imprevisto lato serverNon dipende dal tuo codice. Riprova dopo qualche secondo. Se persiste, contatta il supporto.
502 Bad Gateway / 503 Service UnavailableServizio temporaneamente non disponibileRiprova 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.

json
{
  "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 ​