API
Codici di errore
Guida alla gestione degli errori dell'API di TBit
# 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 richiestaVuoi sapere perché un messaggio di WhatsApp non è stato consegnato? Leggi Errori di consegna su WhatsApp (in spagnolo).
Tutti gli errori seguono una struttura JSON coerente:
{
"error": {
"code": "NOT_FOUND",
"message": "Activity not found"
}
}| 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 |
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 |
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