# Codici di errore

> Guida alla gestione degli errori dell'API di TBit

- Pagina: https://tbit.app/it/docs/api/errors
- URL base: `https://rest-api.tbit.app/v1`
- Autenticazione: header `X-API-Key` con la tua chiave in ogni richiesta (gli esempi la leggono dalla variabile d'ambiente `TBIT_API_KEY`)

Vuoi sapere perché un messaggio di WhatsApp non è stato consegnato? Leggi [Errori di consegna su WhatsApp (in spagnolo)](https://tbit.app/es/docs/errores-de-entrega-whatsapp).

## Formato della risposta di errore

Tutti gli errori seguono una struttura JSON coerente:

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Activity not found"
  }
}
```

## Codici di errore

| Stato | Codice | Descrizione |
| --- | --- | --- |
| `400` | `VALIDATION_ERROR` | Body della richiesta o parametri di query non validi |
| `401` | `UNAUTHORIZED` | Chiave API mancante o non valida |
| `404` | `NOT_FOUND` | Risorsa non trovata o che non appartiene al tuo agente |
| `405` | `METHOD_NOT_ALLOWED` | Metodo HTTP non supportato per questo endpoint |
| `409` | `CONFLICT` | La risorsa esiste già (es. un contatto con questo canale) |
| `422` | `SEND_FAILED` | Invio del modello non riuscito (es. nessuna finestra di messaggistica) |
| `429` | `RATE_LIMITED` | Limite di frequenza superato (100 richieste/minuto) |
| `500` | `INTERNAL_ERROR` | Errore imprevisto del server |

## Header del limite di frequenza

Ogni risposta include negli header le informazioni sul limite di frequenza:

| Header | Descrizione |
| --- | --- |
| `X-RateLimit-Remaining` | Richieste rimanenti nella finestra attuale |
| `X-RateLimit-Reset` | Timestamp (ms) in cui la finestra si azzera |

## Gestione degli errori

Buone pratiche per gestire gli errori dell'API:

- Controlla sempre il codice di stato HTTP prima di analizzare il body della risposta
- Implementa un backoff esponenziale per gli errori 429 (limite di frequenza)
- Registra codici e messaggi di errore per il debug
- Non ritentare gli errori 400 o 401: prima correggi la richiesta