KewbotIn breve
Gli errori della WhatsApp Cloud API arrivano come un numero e un messaggio breve che raramente spiega la causa reale. La maggior parte rientra in cinque famiglie: pagamento e idoneità, policy e consegna, restrizione dell'account, registrazione e numero, e template e contenuto. Qui sotto ci sono i più frequenti, ciascuno con cosa significa e come si risolve. Cerca il numero che ti è comparso nell'indice e vai dritto.
Il problema è il metodo di pagamento o la fatturazione
131042 Business eligibility payment issue
"There is an issue with payment method / business eligibility"
Uno dei più comuni, e significa quasi sempre la stessa cosa: c'è un problema con il metodo di pagamento dell'account WhatsApp Business. Carta scaduta, rifiutata, senza fondi, o una linea di credito di Meta non configurata. Se gestisci account di clienti, è quello che compare quando la carta del cliente non funziona e gli blocca tutti gli invii.
Come si risolveVai nelle impostazioni di fatturazione di WhatsApp nel Business Manager dell'account interessato e controlla il metodo di pagamento: carta valida, verificata e con fondi. Sugli account dei clienti, conferma che la responsabilità di pagamento sia assegnata correttamente. Una volta corretto il pagamento, gli invii ripartono da soli.
141006 Payment issue on the WABA
"There is an error with the payment configuration"
Una variante del precedente, orientata alla configurazione di pagamento della WABA stessa. Il controllo di salute (health_status) segna can_send_message: BLOCKED. Stessa famiglia di radice: l'account non può fatturare, quindi non può inviare.
Come si risolveControlla che la WABA abbia un metodo di pagamento valido e collegato correttamente nel Business Manager. Se hai migrato provider di recente, verifica che la linea di credito o la carta siano rimaste ben collegate al nuovo account.
Meta ha scelto di non consegnare il messaggio
131049 Healthy ecosystem engagement
"This message was not delivered to maintain healthy ecosystem engagement"
L'errore più segnalato in assoluto. Non è un guasto tecnico: Meta ha scelto deliberatamente di non consegnare quel messaggio. Di solito è legato al limite per utente dei template di marketing: se quella persona ha già ricevuto molti template di marketing in poco tempo, Meta interrompe la consegna per non sovraccaricarla. Compare anche quando l'utente ha bassa probabilità di interagire con il marketing.
Come si risolveNon riprovare subito: rinviare immediatamente ripete solo l'errore. Aspetta almeno 24 ore prima di inviare di nuovo quel template a quell'utente. In fondo la soluzione è strategica: invia meno marketing e più rilevante, segmenta meglio, e privilegia i template utility (che non urtano contro questo limite) quando il messaggio è transazionale anziché promozionale.
131026 Message undeliverable
"Message undeliverable"
Un ampio "impossibile consegnare". Le cause tipiche: il numero non è su WhatsApp o non è raggiungibile, il destinatario non ha mai dato l'opt-in per ricevere messaggi dalla tua azienda, o l'account non soddisfa qualche requisito di idoneità per quell'invio. A volte deriva anche da un'incompatibilità di categoria del template.
Come si risolveVerifica che il numero esista su WhatsApp e sia ben formattato (prefisso internazionale incluso, senza il "+" a seconda dell'endpoint). Conferma di avere l'opt-in di quel contatto. Se è un invio massivo che fallisce solo su alcuni, ripulisci la lista dai numeri non validi invece di riprovare in blocco.
L'account è limitato o bloccato
130497 Restricted from messaging in this country
"Business account is restricted from messaging users in this country"
La tua WABA è limitata nell'inviare a utenti di un certo paese. Gli account nuovi possono scrivere solo ai paesi per cui sono stati abilitati; inviare a un paese non autorizzato scatena questo errore. Molto comune all'inizio, quando si prova a scrivere a un numero estero.
Come si risolveL'invio tra paesi si sblocca completando un percorso di scaling e raggiungendo il tier di 2.000 messaggi. Può richiedere fino a 30 giorni per abilitarsi dopo averlo raggiunto. Attenzione: per alcune destinazioni (ad esempio Brasile e Indonesia) potrebbe non abilitarsi nemmeno dopo lo scaling. Nel frattempo, invia solo ai paesi approvati.
131031 Business account locked / restricted
"Business account locked"
L'account è stato limitato o bloccato, di solito per violazioni di policy o discrepanze nella verifica: spam, contenuti che infrangono le regole, o qualcosa che ha attivato la revisione di integrità di Meta. Insieme al 130497 e al 368, forma la famiglia delle restrizioni per integrità/policy.
Come si risolveControlla lo stato dell'account nel Business Manager e nella Qualità dell'account WhatsApp. Se c'è una violazione segnalata, correggi la causa (rallenta gli invii, adegua i contenuti alla policy) e presenta il ricorso dallo stesso pannello. Riprovare l'invio non serve: prima va rimossa la restrizione.
Problemi con il numero, la registrazione o il nome
131037 Display name approval required
"The number used does not have an approved display name"
Il numero da cui invii non ha un nome visualizzato approvato, oppure quello che hai impostato è ancora in attesa di approvazione. Finché il display name non è approvato, non puoi inviare.
Come si risolveImposta il nome visualizzato e attendi l'approvazione di Meta. Assicurati che rispetti le linee guida sui nomi (che corrisponda al tuo brand, senza promozioni né caratteri strani). Se lavori con un BSP, il nome lo gestisce lui.
133005 / 133006 / 133010 Registrazione del numero
"Wrong PIN / re-verification needed / number not registered"
La famiglia 133xxx riguarda la registrazione del numero sulla Cloud API. 133005: PIN di verifica in due passaggi errato. 133006: il numero deve essere ri-verificato. 133010: il numero non è registrato sull'API.
Come si risolvePer il 133005, inserisci il PIN corretto della verifica in due passaggi; se non ce l'hai (tipico quando si migra da un provider fallito), prima bisogna disattivare la verifica in due passaggi dal WhatsApp Manager del proprietario della WABA. Per 133006 e 133010, esegui di nuovo la registrazione del numero sull'API. Questi sono esattamente gli errori che compaiono quando si porta un numero tra provider.
Ritmo di invio, formato e flow
131048 / 130429 Limite di ritmo (spam / rate limit)
"Spam rate limit hit / Rate limit hit"
Stai inviando più velocemente del consentito. 130429 è il limite di frequenza generale; 131048 è il limite di frequenza per spam (Meta ha rilevato un pattern di invio che sembra abuso). Compaiono in campagne grandi mal scaglionate.
Come si risolveAbbassa la cadenza di invio e applica retry con backoff esponenziale (attese sempre più lunghe), non retry immediati. Scaglione le campagne grandi nel tempo. Se è 131048, controlla anche qualità e opt-in: il pattern che ha attivato lo "spam" di solito viene da liste fredde o invii troppo aggressivi.
131053 Media upload error
"Media upload error"
È fallito il caricamento o download del file multimediale (immagine, PDF, audio). Causa frequente: l'URL del file reindirizza (301), richiede una sessione, o il fetcher di media di Meta non è riuscito a scaricarlo. Nei log a volte lo si vede accanto a errori HTTP 500/502 nel download del file dal weblink.
Come si risolveEvita URL che reindirizzano o che dipendono da cookie di sessione: il fetcher di Meta non li segue bene. Servi il file da un URL pubblico e diretto (un oggetto pubblico in un bucket, senza URL firmati o con scadenza). Controlla anche la dimensione e il formato consentiti da WhatsApp.
132018 Parametro del template non valido
"Parameter format mismatch / invalid parameter"
Il contenuto che passi in una variabile del template non rispetta il formato atteso. Caso classico: inviare a capo (\n), tab o certi caratteri dentro una variabile, quando il template non li ammette in quel punto.
Ripulisci il valore della variabile: togli gli a capo e i caratteri di controllo, rispetta il formato (posizionale vs. nominale) con cui è stato creato il template, e non mettere in una variabile contenuto che dovrebbe stare nel corpo fisso. Se ti serve una lista lunga, riformulala perché rientri nel formato consentito.
139000 Blocked by integrity
"Blocked by Integrity" (a volte con subcodice)
Meta ha bloccato un'azione (ad esempio pubblicare un flow) tramite il suo controllo di integrità. Compare di solito con i Flow o operando in modalità sviluppo con permessi incompleti.
Come si risolveVerifica che l'app e l'account abbiano la verifica dell'attività e i permessi completi, e che tu non sia in una limitazione di modalità sviluppo. Se il subcodice indica una limitazione di Dev Mode, completa prima la revisione e approvazione dell'app. Controlla anche che il contenuto del flow non violi la policy.
⚠️ Cosa conviene sempre salvare prima di fare escalation
Quando un errore ti supera e devi fare escalation al supporto, salva sempre questi dati: il codice e messaggio completi, l'error_data.details, il fbtrace_id, il wamid (se Meta ha accettato l'invio), l'ID del numero e della WABA, e se era un template, il suo nome e lingua. Con questo il supporto risolve in un giro; senza, ti chiedono tutto e perdi giorni. Non inviare il contenuto del messaggio a meno che non te lo chiedano esplicitamente.
Domande frequenti
Perché il messaggio dell'errore non spiega la causa reale?
Perché Meta usa messaggi generici di proposito. Lo stesso codice può avere diverse cause concrete, e il testo breve raramente le distingue. Per questo conviene guardare error_data.details e il fbtrace_id, che danno più indizi del titolo.
Ho ricevuto un errore e ho riprovato lo stesso. È sbagliato?
Dipende dall'errore. Quelli di limite (131049, 130429, 131048) peggiorano se riprovi subito: bisogna aspettare e usare il backoff. Quelli di pagamento, restrizione o registrazione non si risolvono riprovando: prima si corregge la causa (pagamento, ricorso, ri-registrazione).
Esiste una lista ufficiale e completa di tutti i codici?
Sì, Meta pubblica il riferimento completo nella documentazione della Cloud API, e cambia nel tempo (aggiungono codici nuovi, come il 131064). Questa guida copre quelli che compaiono di più nella pratica, non le centinaia che esistono. Per uno raro, il riferimento ufficiale è la fonte.
Molti dei miei errori sono di pagamento o restrizione. Cosa faccio?
Se si ripetono, di solito è un segnale che l'account ha bisogno di ordine: metodo di pagamento ben configurato, qualità e opt-in sani, e scaling dei limiti fatto come si deve. Risolvere la radice una volta evita che tornino a catena.
Bloccato su un errore che non cede?
Facciamo onboarding e gestiamo account su WhatsApp Business API, con accesso al supporto diretto di Meta per fare escalation dei casi che lo richiedono. Se stai combattendo con un errore, scrivici e lo guardiamo.
Vai a Kewbot →