Errori di autenticazione e autorizzazione
Errore 401 Unauthorized: l'API key non e valida o e stata revocata. Verifica che l'API key nel tuo ambiente sia quella corretta e che non sia scaduta. In ambienti con variabili d'ambiente multiple (dev, staging, prod), e facile usare la chiave sbagliata.
Errore 403 Forbidden: hai l'API key valida ma non hai i permessi per l'operazione richiesta. Verifica che il tuo account abbia accesso alla feature che stai cercando di usare.
Errori di invio messaggi
Errore 400 con 'recipient not on WhatsApp': il numero di telefono del destinatario non ha WhatsApp attivo. Verifica sempre che il numero sia nel formato internazionale corretto e considera di implementare una verifica preventiva con l'API di lookup.
Errore 400 con 'template not found': il nome del template nel payload non corrisponde a nessun template approvato per il numero di telefono. I nomi dei template sono case-sensitive e devono corrispondere esattamente.
Errore 429 Too Many Requests: hai superato il rate limit dell'API. Implementa un backoff esponenziale e distribuisci gli invii nel tempo. Per i broadcast a grandi volumi, usa la coda di invio di Chat API.
Errori webhook
Webhook non ricevuto: verifica che il tuo endpoint sia raggiungibile pubblicamente (non localhost), che risponda con un 200 OK entro 20 secondi, e che la firma nell'header sia verificata correttamente.
Strumenti di debug
Usa la dashboard di Chat API per monitorare i messaggi inviati e i loro stati (pending, sent, delivered, read, failed). Per i fallimenti, il dettaglio dell'errore e visibile nel log del messaggio.
Per i test in locale, usa ngrok per esporre il tuo endpoint webhook locale. Usa uno strumento come Postman o HTTPie per testare le chiamate API manualmente prima di implementarle nel codice.
