# Errori API

[Versione web](https://docs.hive-service.com/api/errori)

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

```json
{
  "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:

```json
{
  "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.
