Errori API

L'API comunica gli errori con codici di stato HTTP standard e un corpo di risposta uniforme. Le risposte con successo restituiscono i dati direttamente, senza envelope.

Formato dell'errore

In caso di errore, il corpo della risposta è un oggetto JSON con un solo campo error contenente un messaggio leggibile dall'uomo:

{"error":"reaction not found"}

Affidati principalmente al codice di stato HTTP; il testo error usalo per i log e i messaggi all'utente.

Codici di stato

  • 200 OK — richiesta riuscita, nel corpo ci sono i dati.
  • 201 Created — creata una nuova risorsa (alcune endpoint POST).
  • 204 No Content — successo senza corpo (alcune cancellazioni).
  • 400 Bad Request — corpo o parametri della richiesta non validi.
  • 401 Unauthorized — token assente, errato o scaduto; oppure la route non è accessibile con il token personale.
  • 402 Payment Required — l'azione è bloccata dal piano o dalla quota (ad esempio, lo storage media proprio richiede il premium).
  • 403 Forbidden — al token manca l'ambito necessario per questa route.
  • 404 Not Found — risorsa non trovata o non appartenente all'utente.
  • 409 Conflict — conflitto di stato (ad esempio, duplicato di un valore univoco).
  • 422 Unprocessable Entity — il corpo è sintatticamente valido ma non supera i controlli del dominio.
  • 429 Too Many Requests — limite di richieste superato (vedi limiti).
  • 500 Internal Server Error — errore interno del server; riprova più tardi.

Come gestire gli errori

Considera successo i codici 2xx. Su 401/403 verifica il token e i suoi ambiti. Su 4xx (tranne 429) non ripetere la richiesta senza modifiche — correggi la richiesta. Su 429 e 5xx è opportuno riprovare con backoff esponenziale.

Passo successivo