Gestione degli errori delle API Hive

Quando è presente un body, le API restituiscono normalmente questo formato:

{
  "status": "BAD_REQUEST",
  "message": "Descrizione dell'errore",
  "errors": "Dettagli dell'errore"
}

status è il nome dello stato HTTP, per esempio BAD_REQUEST o NOT_FOUND.
message contiene una descrizione leggibile dell’errore.
errors contiene i dettagli e può essere una stringa, una lista di errori di validazione o un oggetto strutturato.

Consulta la singola operazione nella reference per gli status e gli esempi specifici. Alcune risposte costruite senza contenuto non includono un body.

Status di errore

Status	Significato generale	Indicazione
`400`	Richiesta o parametri non validi	Correggi i dati inviati prima di riprovare.
`401`	Credenziale API non valida	Verifica `clientId` e `clientSecret`.
`403`	Operazione non consentita	Verifica le autorizzazioni dell’utente.
`404`	Risorsa non trovata	Controlla identificativi e parametri.
`409`	Conflitto con lo stato corrente	Aggiorna i dati o lo stato della risorsa prima di riprovare.
`500`	Errore interno	Conserva il contesto tecnico e contatta l’assistenza se persiste.
`502`	Errore di un servizio esterno	Riprova più tardi o contatta l’assistenza.
`503`	Servizio temporaneamente non disponibile	Attendi e riprova.

Esempio: numero già attivo

POST /v1/numbers/activate restituisce 400 Bad Request quando il numero è già attivo oppure è stato eliminato:

{
  "status": "BAD_REQUEST",
  "message": "Number already active or deleted",
  "errors": "Number already active or deleted"
}

Diagnostica

Quando segnali un problema, includi timestamp, ambiente, metodo HTTP, path e status ricevuto. Anonimizza il payload e non condividere API key, access token o dati personali.

Esegui retry automatici soltanto quando conosci l’idempotenza dell’operazione e puoi escludere che una scrittura sia già stata applicata.