Codici di errore WhatsApp Cloud API: significato e soluzioni

Questa guida è pensata per sviluppatori e team operativi di messaggistica che vedono messaggi WhatsApp non riusciti e devono capire in fretta se correggere la richiesta, attendere, cambiare tipo di messaggio o fermarsi. Ogni codice qui sotto è stato verificato rispetto al riferimento dei codici di errore della Cloud API di Meta; codici e formulazioni cambiano, quindi confermate su quella pagina prima di codificare la logica.

Dove compaiono gli errori della WhatsApp Cloud API?

Gli errori compaiono in due punti e dovete catturarli entrambi. Gli errori di richiesta tornano subito nella risposta dell'API; gli errori di consegna arrivano più tardi in un webhook di stato.

• Errori sincroni. La richiesta di invio viene rifiutata e la risposta contiene un oggetto error con code, message, type e spesso error_data.details. Esempi tipici sono token scaduti, parametri mancanti e discordanze con il template.
• Errori asincroni. La richiesta di invio ha successo e restituisce un ID messaggio, ma un webhook successivo segnala status: failed con un array errors. Esempi tipici sono finestre di assistenza chiuse, destinatari non raggiungibili e limiti di marketing.

Un errore comune è registrare solo la risposta HTTP. I team credono allora che una campagna sia riuscita perché ogni richiesta ha restituito un ID messaggio, mentre centinaia di messaggi sono falliti nei webhook. Per capire come si collegano gli stati, vedi sent, delivered, read e failed spiegati.

Quali sono i codici di errore WhatsApp più comuni?

La tabella elenca i codici che la maggior parte dei team incontra, raggruppati per ciò che dovete fare dopo. Le descrizioni parafrasano il riferimento di Meta.

Come risolvere gli errori che causano la maggior parte delle campagne fallite?

In pratica, pochi codici causano la maggior parte dei fallimenti. Ognuno ha una regola decisionale chiara.

131047: la finestra di assistenza è chiusa

Il cliente ha scritto l'ultima volta più di 24 ore fa. Testo libero, media e messaggi interattivi sono consentiti solo all'interno della finestra di assistenza clienti di 24 ore; fuori da essa dovete usare un template approvato; vedi la finestra di assistenza clienti di 24 ore. Gli agenti incappano spesso in questo errore rispondendo a una chat vecchia. Mostrate agli agenti lo stato della finestra e offrite un selettore di template quando è scaduta.

131026: messaggio non consegnabile

Partite dall'igiene dei numeri: formato internazionale, prefisso corretto, nessuno zero iniziale dopo il prefisso. Poi accettate che alcuni numeri semplicemente non sono su WhatsApp, o hanno una versione dell'app obsoleta. Per i messaggi urgenti come gli OTP, ripiegate sugli SMS. Vedi WhatsApp vs SMS vs RCS.

131049 e 131050: limiti di marketing e disiscrizioni

Entrambi riguardano i messaggi di marketing. 131050 è la scelta esplicita dell'utente di interrompere il marketing; escludeteli dal marketing e sottoscrivete il webhook delle preferenze utente di Meta. 131049 significa che Meta ha scelto di non consegnare per proteggere il coinvolgimento degli utenti; Meta consiglia di attendere almeno 24 ore e tentativi più ravvicinati probabilmente falliranno di nuovo. Riducete la frequenza e migliorate la pertinenza invece di reinviare.

130429, 131048 e 131056: invio troppo veloce o eccessivo

130429 riguarda il throughput: mettete i messaggi in coda e applicate il backoff. 131056 riguarda la coppia mittente-destinatario: state scrivendo troppo spesso a una persona. 131048 è un segnale di qualità sul numero mittente e richiede una correzione di contenuti e targeting, non un nuovo tentativo. Vedi limiti di messaggistica e quality rating.

132000, 132001 e 132012: discordanze nei template

Quasi sempre si tratta di bug di integrazione. Il nome del template, il codice lingua (ad esempio ar rispetto a en_US) e il numero di variabili devono corrispondere esattamente a quanto approvato. Create un test che invii ogni template con valori di esempio ogni volta che lo modificate.

Una policy di nuovo tentativo che potete implementare

Usate questa checklist per classificare automaticamente ogni fallimento.

1. Registrate codice, titolo, error_data.details, ID messaggio, destinatario e nome del template.
2. Non riprovate mai 131050, 131021, 132016, 368 e 131031. Segnalate subito 368 e 131031 a un amministratore.
3. Correggete e poi riprovate gli errori di autorizzazione (0, 190, 10), di parametri (131008, 131009, 135000), di template (da 132000 a 132015) e di fatturazione (131042). Avvisate il team responsabile.
4. Applicate backoff e riprovate 130429, 4, 80007, 131016 e 131057 con backoff esponenziale e un tetto.
5. Cambiate canale o tipo di messaggio per 131047 (template) e 131026 (SMS o email).
6. Attendete 24 ore o più per 131049 e rivedete la frequenza delle campagne.
7. Riportate i fallimenti per codice nei report delle campagne, non come un unico totale "failed".

Esempio pratico: la promozione fallita di un rivenditore di Riyadh

Un esempio di fantasia. "Najd Home" invia un template di marketing a 20.000 clienti che hanno dato il consenso. L'API accetta ogni richiesta, ma i webhook di stato mostrano circa 1.400 fallimenti.

Raggruppati per codice, il quadro è chiaro. Il gruppo più grande è 131049, quindi il team rimuove quegli utenti dai due invii successivi e riduce la frequenza settimanale. Un gruppo più piccolo è 131026; l'analisi mostra molti numeri memorizzati con uno zero iniziale locale, che una correzione di normalizzazione risolve. Diversi utenti 131050 vengono esclusi in modo permanente dal marketing. Alcuni errori 130429 derivavano dalla raffica iniziale, quindi l'invio ora è dosato tramite una coda.

Errori comuni e limiti onesti

• Trattare ogni fallimento come ritentabile. Spreca denaro e può abbassare la qualità.
• Codificare i testi di Meta. Meta aggiorna titoli e descrizioni; basate la logica sul codice numerico e mantenete una tabella di corrispondenza aggiornabile.
• Ignorare error_data.details. Indica spesso il parametro difettoso esatto.
• Non ogni fallimento ha una soluzione. Alcuni destinatari non sono raggiungibili su WhatsApp e Meta non spiega ogni decisione 131049. Pianificate un canale alternativo.

Come vi aiuta OmniChannels.ai

OmniChannels.ai, basato su BroadNet Technologies, offre ai team rapporti di consegna in viste di sintesi e avanzate, con filtri ed esportazione CSV, così i messaggi falliti possono essere analizzati per campagna. Il fallback tra canali può reinviare tramite RCS o SMS quando WhatsApp fallisce, e i template hanno un'anteprima su mock-up di telefono e un monitoraggio dell'approvazione, riducendo gli errori di discordanza. I webhook segnalano gli stati FAILED e REJECTED in un unico formato normalizzato, e la documentazione per sviluppatori pubblica comprende un riferimento su errori e limiti.