Soluzioni agli Errori API WhatsApp: Guida Completa per Risolvere i Problemi più Comuni

Cosa sono gli errori API WhatsApp e come risolverli rapidamente

In sintesi: gli errori API WhatsApp sono risposte di errore restituite dalla piattaforma Meta quando una richiesta di invio messaggio, registrazione numero o gestione template non va a buon fine. I codici più comuni includono il 131030 (limite di frequenza superato), il 131047 (numero non registrato su WhatsApp), il 131051 (template non approvato o sospeso) e il 100 (parametri mancanti o malformati). Ogni errore ha una causa specifica e una soluzione distinta: il 131030 richiede di rispettare i tier di messaggistica e aumentare gradualmente il volume; il 131047 impone una verifica del numero destinatario prima dell'invio; il 131051 richiede la revisione e la ri-sottomissione del template a Meta; il codice 100 indica un problema nel payload della richiesta HTTP. Identificare il codice esatto, leggere il campo 'error_data' nella risposta JSON e agire sulla causa radice è il metodo più efficace per risolvere il 90% dei problemi senza escalation al supporto.

La maggior parte degli errori API WhatsApp si divide in due macro-categorie: errori lato mittente (configurazione account, template, payload) ed errori lato destinatario (numero non valido, utente che ha bloccato il numero aziendale, finestra di conversazione scaduta). Distinguere le due categorie è fondamentale perché le azioni correttive sono completamente diverse: un errore lato mittente richiede intervento tecnico o di configurazione, mentre un errore lato destinatario richiede una strategia di re-engagement o la pulizia del database contatti.

Per le aziende che usano WhatsApp Business API tramite una piattaforma come Kuba Labs, molti di questi errori vengono gestiti automaticamente dall'infrastruttura: i retry intelligenti, il monitoraggio dei template e la gestione dei rate limit sono inclusi nel servizio. Tuttavia, capire la logica sottostante permette ai team marketing e tecnici di configurare flussi più robusti, evitare sospensioni dell'account e massimizzare il tasso di consegna dei messaggi.

Quali sono i codici di errore WhatsApp API più frequenti?

Meta classifica gli errori API WhatsApp in gruppi numerici che seguono una logica precisa. I codici nella fascia 100-199 riguardano errori di parametri e autenticazione: il 100 indica parametri non validi nel corpo della richiesta, il 190 segnala un token di accesso scaduto o non valido. Questi errori sono quasi sempre risolvibili lato sviluppatore controllando la struttura del payload e rinnovando il token di accesso tramite il pannello Meta Business.

I codici nella fascia 130000-131999 sono specifici delle API Cloud di WhatsApp Business e coprono scenari operativi più complessi. Il 130429 indica che il rate limit dell'account è stato superato e i messaggi vengono temporaneamente bloccati: la soluzione è attendere il reset della finestra temporale o richiedere un aumento del tier di messaggistica. Il 131000 è un errore generico di sistema che richiede un retry dopo qualche secondo. Il 131026 segnala che il messaggio non è stato consegnato perché il destinatario ha un numero non valido o non usa WhatsApp.

Un caso a parte è il codice 131051, che indica un template rifiutato o in stato di pausa. Meta può sospendere un template se riceve un numero elevato di segnalazioni negative dagli utenti o se il contenuto viola le policy. In questo caso la soluzione non è tecnica ma editoriale: bisogna rivedere il testo del template, eliminare elementi percepiti come spam, e ri-sottometterlo per approvazione. Monitorare il quality rating dei template nel pannello Meta Business Manager è la prevenzione più efficace.

• Codice 100: parametri mancanti o malformati nel payload
• Codice 190: token di accesso scaduto o revocato
• Codice 130429: rate limit superato, attendere o aumentare il tier
• Codice 131026: numero destinatario non valido o non su WhatsApp
• Codice 131030: limite giornaliero di messaggi raggiunto
• Codice 131047: numero mittente non registrato correttamente
• Codice 131051: template sospeso o non approvato da Meta
• Codice 131000: errore generico di sistema, retry consigliato

Come risolvere l'errore 131030: limite di messaggi superato

Il codice 131030 è uno degli errori più comuni per le aziende ecommerce che lanciano campagne di notifica su larga scala. Indica che il numero di telefono aziendale ha raggiunto il limite giornaliero di messaggi consentito dal tier di messaggistica attuale. WhatsApp Business API utilizza un sistema a livelli: Tier 1 consente 1.000 conversazioni uniche al giorno, Tier 2 ne consente 10.000, Tier 3 arriva a 100.000. Il passaggio da un tier all'altro avviene automaticamente se si rispettano determinate condizioni di qualità e volume.

Per risolvere il 131030 nel breve termine, la soluzione immediata è interrompere l'invio e riprendere il giorno successivo quando il contatore si azzera. Nel medio termine, per scalare il volume è necessario aumentare gradualmente il numero di messaggi inviati nell'arco di 7 giorni senza ricevere segnalazioni negative, mantenere un quality rating 'Green' o 'Yellow' nel pannello Meta, e assicurarsi che il numero aziendale sia verificato. Meta promuove automaticamente al tier superiore i numeri che soddisfano questi criteri.

Una strategia preventiva efficace è distribuire gli invii nell'arco della giornata invece di concentrarli in un'unica finestra temporale. Le piattaforme come Kuba Labs gestiscono questo aspetto con code di invio intelligenti che rispettano i limiti di rate e distribuiscono automaticamente i messaggi per evitare il raggiungimento del tetto giornaliero. Questo è particolarmente rilevante durante eventi ad alto volume come Black Friday, lanci di prodotto o campagne di recupero carrelli abbandonati.

Perché i template WhatsApp vengono rifiutati e come correggerli

I template WhatsApp Business devono essere approvati da Meta prima di poter essere utilizzati per inviare messaggi al di fuori della finestra di conversazione di 24 ore. Il rifiuto avviene quando il contenuto viola le policy di Meta: testi che contengono promesse di guadagno, linguaggio ingannevole, riferimenti a contenuti per adulti, o semplicemente un formato non conforme alle linee guida. Il motivo del rifiuto viene indicato nel pannello Meta Business Manager con una categoria di violazione.

Le cause più frequenti di rifiuto includono: variabili non contestualizzate (es. usare {{1}} senza che il contesto renda chiaro cosa rappresenta), call-to-action che rimandano a URL non verificati, testi che sembrano messaggi promozionali non sollecitati, e template nella categoria sbagliata (es. un messaggio transazionale classificato come marketing). La correzione richiede di modificare il testo rispettando le linee guida, verificare che le variabili abbiano esempi chiari, e ri-sottomettere il template. I tempi di revisione di Meta variano da poche ore a 24 ore.

Un errore meno ovvio è la sospensione di un template precedentemente approvato. Questo accade quando il template riceve un tasso di segnalazione negativa superiore alla soglia tollerata da Meta. In questo caso il template passa in stato 'Paused' e smette di funzionare. La soluzione è analizzare il contenuto per capire perché gli utenti lo segnalano come spam, modificarlo per renderlo più pertinente e personalizzato, e ri-attivarlo. Aggiungere il nome del destinatario e riferimenti specifici all'ordine o all'interazione precedente riduce significativamente le segnalazioni negative.

• Verificare che ogni variabile abbia un esempio concreto nel campo 'example'
• Usare URL verificati e appartenenti al dominio aziendale registrato su Meta
• Evitare linguaggio promozionale aggressivo nei template transazionali
• Classificare correttamente il template: Utility, Marketing o Authentication
• Controllare il quality rating del template nel pannello Meta Business Manager
• Non superare il limite di pulsanti CTA consentiti per categoria

Come gestire gli errori di autenticazione e token scaduti

Gli errori di autenticazione, in particolare il codice 190, si verificano quando il token di accesso utilizzato per le chiamate API è scaduto, revocato o non ha i permessi necessari. I token di accesso utente di Meta hanno una scadenza di default di 60 giorni, mentre i token di sistema generati tramite un'app Meta Business possono essere configurati come token a lunga durata o permanenti. Per ambienti di produzione, l'uso di token di sistema permanenti è la pratica raccomandata per evitare interruzioni del servizio.

Per risolvere il codice 190, il primo passo è verificare nel pannello Meta Business Manager se il token è ancora valido e se l'app ha i permessi 'whatsapp_business_messaging' e 'whatsapp_business_management' attivi. Se il token è scaduto, va rigenerato e aggiornato in tutti i sistemi che lo utilizzano: CRM, piattaforma di automazione, webhook. Un errore comune è aggiornare il token solo in un sistema e dimenticare le integrazioni secondarie, causando errori intermittenti difficili da diagnosticare.

Le piattaforme BSP (Business Solution Provider) come Kuba Labs gestiscono l'autenticazione in modo trasparente per il cliente: il token viene rinnovato automaticamente e le credenziali sono gestite a livello di infrastruttura. Questo elimina una delle cause più frequenti di interruzione del servizio per i team tecnici che gestiscono integrazioni custom. Per chi invece gestisce un'integrazione diretta con le API Meta, è consigliabile implementare un sistema di monitoraggio che avvisi proattivamente quando un token è prossimo alla scadenza.

Errori di consegna: quando il messaggio non arriva al destinatario

Gli errori di consegna sono diversi dagli errori API: l'API accetta la richiesta (risponde con un message ID), ma il messaggio non viene effettivamente consegnato all'utente. Questo si manifesta con lo stato 'failed' o 'undelivered' nel webhook di status update. Le cause principali sono: il destinatario ha disinstallato WhatsApp, il numero non è più attivo, l'utente ha bloccato il numero aziendale, o il dispositivo del destinatario è offline da troppo tempo e il messaggio è scaduto.

Per gestire questi errori è fondamentale implementare un sistema di ascolto dei webhook di stato. Meta invia aggiornamenti di stato per ogni messaggio: 'sent' (inviato al server Meta), 'delivered' (consegnato al dispositivo), 'read' (letto dall'utente), 'failed' (fallito con codice errore). Monitorare questi stati permette di identificare numeri non validi nel database, segmentare i contatti non raggiungibili, e attivare flussi alternativi come email o SMS per i messaggi critici.

Un caso specifico è l'errore legato alla finestra di conversazione di 24 ore. Se un utente non ha inviato un messaggio nelle ultime 24 ore, è possibile contattarlo solo con template pre-approvati. Se si tenta di inviare un messaggio libero fuori da questa finestra, l'API restituisce un errore specifico. La soluzione è sempre usare template approvati per le comunicazioni outbound e riservare i messaggi liberi alle risposte all'interno della finestra attiva.

• Implementare webhook listener per ricevere aggiornamenti di stato in tempo reale
• Classificare i contatti in base allo stato di consegna: raggiungibili, non raggiungibili, bloccati
• Usare sempre template approvati per messaggi outbound fuori dalla finestra 24h
• Pulire periodicamente il database rimuovendo numeri con errori ripetuti di consegna

Come prevenire gli errori API con una configurazione robusta

La prevenzione degli errori API WhatsApp inizia dalla fase di configurazione dell'account e dell'integrazione. I punti critici da verificare prima di andare in produzione includono: la verifica del numero di telefono aziendale tramite il processo ufficiale Meta, la configurazione corretta del webhook con un endpoint HTTPS valido e un token di verifica, la creazione di template in tutte le lingue necessarie con esempi di variabili completi, e il test dell'integrazione con la WhatsApp Business API Test Tool disponibile nel pannello Meta.

Un'altra pratica fondamentale è implementare una logica di retry con backoff esponenziale per gli errori temporanei come il 131000 o il 130429. Invece di ritentare immediatamente, il sistema dovrebbe aspettare 1 secondo al primo retry, 2 al secondo, 4 al terzo, e così via. Questo evita di sovraccaricare ulteriormente il sistema e rispetta i limiti di rate. Per gli errori permanenti come il 131026 (numero non valido), il retry non ha senso e il contatto va marcato come non raggiungibile.

Il monitoraggio proattivo è l'ultimo pilastro della prevenzione. Configurare alert automatici per: tasso di errore superiore al 5% sugli invii, quality rating del numero che scende a 'Red', template che entrano in stato 'Paused', e token di accesso prossimi alla scadenza. Questi alert permettono di intervenire prima che un problema tecnico diventi un'interruzione del servizio con impatto sul business. Kuba Labs include dashboard di monitoraggio e notifiche proattive per tutti questi scenari nell'abbonamento standard.

Errori API WhatsApp per ecommerce: i casi d'uso più critici

Per un ecommerce, gli errori API WhatsApp hanno un impatto diretto sul fatturato perché interrompono flussi critici come le notifiche di ordine, i messaggi di recupero carrello abbandonato, le conferme di spedizione e i promemoria di reso. Un errore 131051 su un template di conferma ordine, ad esempio, significa che i clienti non ricevono la notifica di acquisto e il tasso di contatto al customer service aumenta. Identificare e risolvere questi errori entro poche ore è prioritario.

Il flusso di recupero carrello abbandonato è particolarmente sensibile agli errori di rate limit: se una campagna viene lanciata su migliaia di contatti contemporaneamente senza rispettare i tier di messaggistica, si attiva il codice 131030 e la campagna si interrompe a metà. La soluzione è pianificare le campagne con invii scaglionati e verificare in anticipo il tier attuale del numero aziendale. Con Kuba Labs, che parte da 9€/mese nel Tier 0 e scala con il volume, la gestione dei tier è automatizzata e i costi Meta sono inclusi nell'abbonamento, eliminando sorprese sui costi di infrastruttura.

Un caso d'uso critico spesso sottovalutato è la gestione degli errori nei flussi di notifica post-acquisto durante i picchi stagionali. Durante il Black Friday o le campagne natalizie, il volume di messaggi può moltiplicarsi di 10-20 volte rispetto alla media. Preparare l'infrastruttura in anticipo significa verificare il tier di messaggistica almeno 2 settimane prima, testare tutti i template in uso, e configurare flussi di fallback su email per i messaggi che non vengono consegnati su WhatsApp. Questa preparazione riduce il rischio di errori critici nei momenti di maggiore impatto sul fatturato.

• Verificare il tier di messaggistica almeno 2 settimane prima di campagne ad alto volume
• Configurare flussi di fallback su email per messaggi critici non consegnati
• Monitorare il quality rating del numero durante i picchi stagionali
• Testare tutti i template attivi prima di ogni campagna importante
• Implementare alert sul tasso di errore per intervenire entro poche ore