Errori di WhatsApp Business API: cosa significa ogni codice e come risolverlo

WhatsApp Business API che non funziona: controlla prima queste cinque cose

Quando tutti i messaggi si fermano insieme, la causa è quasi sempre una di cinque cose, e puoi controllarle tutte in pochi minuti. Seguile in quest'ordine, perché i primi controlli riguardano ogni messaggio e l'ultimo riguarda i singoli clienti.

1. 1

   Controlla la pagina di stato di Meta

   Apri la pagina di stato della WhatsApp Business API di Meta. Se Meta segnala un problema, aspetta che si risolva prima di cambiare le impostazioni. I codici 1, 2, 131016 e 133004 rimandano a questo caso.
2. 2

   Controlla lo stato del tuo numero in Whapi

   Nella dashboard di Whapi dentro Shopify, il tuo numero WhatsApp dovrebbe mostrare uno stato verde. Meta invia e riceve messaggi solo per i numeri con lo stato Connected. Se non è connesso, fai clic su Connect WhatsApp e ricollegalo.
3. 3

   Controlla il metodo di pagamento in Meta

   Apri WhatsApp Manager e cerca un invito ad Add payment method nella pagina Overview. Senza un metodo di pagamento valido, i messaggi modello falliscono, spesso con l'errore 131042. Segui la guida al metodo di pagamento.
4. 4

   Controlla lo stato del modello

   Ogni automazione Whapi invia un modello che Meta deve approvare. Un modello ancora in revisione, rifiutato o in pausa fallisce con 132001, 132015 o 132016. Vedi perché i modelli vengono rifiutati.
5. 5

   Controlla il numero del cliente

   Se solo alcuni clienti non ricevono i messaggi, guarda il codice sul messaggio fallito. 131026 significa che il numero non può ricevere messaggi WhatsApp, 131047 che la finestra di 24 ore è chiusa, 131049 e 131050 riguardano i messaggi di marketing.

Errori di configurazione e connessione

Gli errori di configurazione compaiono nel popup di registrazione di Meta dopo aver fatto clic su Connect WhatsApp in Whapi. Provengono dal flusso Embedded Signup di Meta, quindi la formulazione qui sotto è quella di Meta e la soluzione si trova dal lato Meta o WhatsApp.

«Your phone number isn’t eligible to connect to the WhatsApp Business Platform»

È il codice 3441045 di Meta, mostrato quando colleghi il numero di una WhatsApp Business App. L'unica soluzione indicata da Meta è che serve più attività sulla WhatsApp Business App per stabilire l'idoneità, e non pubblica alcun minimo. La guida al numero di telefono non idoneo spiega cosa fare e descrive gli errori di verifica correlati.

«This number is registered to an existing WhatsApp account»

Meta lo mostra quando il numero è già in uso su WhatsApp Messenger, sulla WhatsApp Business App o sulla WhatsApp Business API. Se il numero è sulla WhatsApp Business App e vuoi continuare a usarla, scegli invece Connect a WhatsApp Business App nella configurazione di Whapi (è la coexistence di WhatsApp). Per usare il numero solo sull'API, elimina prima l'account WhatsApp dal telefono. Secondo Meta, il numero può impiegare fino a 3 minuti per diventare disponibile.

«The business is already sharing this WhatsApp Business account with a partner»

È il codice 2655093. Il numero della tua WhatsApp Business App è ancora collegato a un altro provider, e Meta non supporta il cambio di partner in questo flusso. Scollega il partner attuale nella WhatsApp Business App da Settings > Account > Business Platform, aspetta 15 minuti, poi collega di nuovo. La guida per spostare il tuo numero su Whapi copre sia i numeri in coexistence sia quelli solo API.

Il popup di Meta non si apre o si chiude a metà

La registrazione di Meta funziona in una finestra popup. Esegui la configurazione di Whapi da un computer, consenti i popup per l'admin di Shopify nel browser e ricarica la pagina. Se Meta dice «Your Facebook account is too new to create a business account. Try again in an hour», aspetta oppure accedi con un account Facebook più vecchio e attivo. Se dice «User does not have permission to create WhatsApp Business Accounts», ti serve l'accesso Admin al portfolio aziendale che hai selezionato.

Nome visualizzato rifiutato

Meta controlla il tuo nome visualizzato di WhatsApp in base alle sue linee guida sui nomi visualizzati. Se la registrazione dice «Your verified name violates WhatsApp guidelines. Please edit your verified name and try again», consulta le linee guida sui nomi visualizzati e inserisci un nome che le rispetti. Puoi cambiare un nome visualizzato fino a 10 volte in 30 giorni in WhatsApp Manager, da Account tools > Phone numbers > Profile. L'errore 131037 si applica solo ai numeri aziendali 555 forniti da Meta senza un nome visualizzato approvato.

Verifica aziendale e limiti sui numeri

Un nuovo portfolio aziendale può registrare due numeri di telefono aziendali. Meta alza questo tetto a 20 una volta che l'attività è verificata o raggiunge un limite di messaggistica di 2.000. Finché la verifica non è completata, Meta limita anche quanti account WhatsApp Business puoi creare (codice 2388098). Vedi verifica aziendale di Meta per WhatsApp per documenti e passaggi.

Errori di pagamento e fatturazione

L'errore 131042, «There was an error related to your payment method», significa che Meta non può addebitare l'account Messaging che invia i tuoi messaggi. L'elenco di cause di Meta comprende nessun account di pagamento collegato, una linea di credito oltre il limite, un account WhatsApp Business eliminato o sospeso e un fuso orario o una valuta mai impostati.

Dal 1° ottobre 2026, un metodo di pagamento mancante blocca anche i messaggi di servizio una volta esauriti i 1.000 gratuiti per numero aziendale al mese, e i modelli Utility inviati all'interno di una finestra di 24 ore aperta vengono addebitati. L'articolo sulla modifica dei prezzi di ottobre 2026 ne spiega i dettagli.

La guida al metodo di pagamento spiega come aggiungere una carta in WhatsApp Manager e gli errori sulla carta che Meta mostra, come «Couldn’t save payment method». I prezzi dei messaggi per paese sono nella pagina sui prezzi di WhatsApp API.

Errori di consegna dei messaggi

Gli errori di consegna riguardano un cliente o un messaggio alla volta, quindi gli altri messaggi continuano a partire. Considerali un'informazione su quel cliente ed evita di riprovare lo stesso messaggio di continuo.

131026: messaggio non consegnabile

Meta indica tre motivi: il numero non è un numero WhatsApp, il cliente non ha accettato gli ultimi Termini di servizio di WhatsApp, oppure l'app del cliente è più vecchia del minimo supportato da Meta. Se una conferma d'ordine fallisce, chiama o scrivi al cliente con un altro mezzo. La guida all'errore 131026 elenca i controlli.

131047: finestra di 24 ore chiusa

Le risposte libere sono consentite solo entro 24 ore dall'ultimo messaggio del cliente. Dopo, invia un modello approvato. Leggi di più su errore 131047 e finestra di assistenza clienti.

131049 e 131050: messaggi di marketing trattenuti

131049 significa che Meta ha limitato i modelli di marketing verso quel cliente «to maintain healthy ecosystem engagement»; aspetta almeno 24 ore prima di reinviare. 131050 significa che il cliente ha scelto di non ricevere più messaggi di marketing dalla tua attività, quindi non riprovare. Entrambi riguardano i modelli di marketing. Vedi la guida all'errore 131049.

130429 e 131056: invio troppo veloce

130429 significa che è stato raggiunto il throughput dei messaggi del numero; riprova più tardi. 131056 significa che troppi messaggi sono andati allo stesso cliente in poco tempo; aspetta prima di scrivergli di nuovo, mentre gli altri clienti non sono interessati.

131021: test inviato al tuo stesso numero aziendale

Meta non consegna un messaggio da un numero a se stesso. Quando usi Send Test Message in Whapi, inserisci un numero WhatsApp personale diverso dal numero aziendale.

Errori dei modelli

Gli errori dei modelli significano che Meta non ha approvato il modello, che le variabili nel messaggio non corrispondono, oppure che Meta lo ha messo in pausa perché i clienti lo hanno bloccato o segnalato. Whapi invia i modelli a Meta quando configuri un'automazione, e Meta decide categoria e approvazione.

• 132001: il modello non esiste in quella lingua o non è approvato. Controlla il suo stato in Whapi o in WhatsApp Manager.
• 132000 e 132012: le variabili inviate non corrispondono al numero o al formato del modello. Falle corrispondere, oppure invia all'assistenza Whapi il nome dell'automazione.
• 132005: una traduzione è troppo lunga. Accorcia quella versione linguistica.
• 132007: il contenuto viola una policy di WhatsApp. Vedi perché Meta rifiuta i modelli.
• 132015 e 132016: in pausa per bassa qualità, poi disattivato in modo permanente dopo pause ripetute. Modifica un modello in pausa; sostituisci uno disattivato con un nuovo contenuto.
• 131064: l'account ha raggiunto un limite di messaggistica per violazioni nella classificazione dei modelli. Assicurati che gli aggiornamenti sugli ordini siano scritti come Utility e le promozioni come Marketing. La guida Utility e Marketing spiega la differenza.
• 2388019: l'account ha già il massimo di 250 modelli. Elimina quelli che non usi più.
• Modello ricategorizzato come Marketing: non esiste un codice di errore per questo caso. Dal 9 aprile 2025, un modello inviato come Utility che Meta ritiene di marketing viene approvato come Marketing, e Meta può anche cambiare in seguito la categoria di un modello approvato. I contenuti misti, come un aggiornamento d'ordine con un codice sconto, contano come marketing. Puoi richiedere una revisione entro 60 giorni dal cambio di categoria.

Quality rating, limiti di messaggistica e restrizioni dell'account

Meta abbassa i limiti o limita un numero quando i clienti bloccano o segnalano i suoi messaggi, oppure quando l'attività viola una policy di WhatsApp Business. Whapi usa la WhatsApp Business API ufficiale di Meta, che evita i blocchi provocati dagli strumenti non ufficiali basati su WhatsApp Web, ma Meta può comunque limitare qualsiasi numero che violi le sue policy.

Limiti di messaggistica

Un limite di messaggistica fissa quanti clienti unici puoi contattare al di fuori di una finestra di assistenza clienti in un periodo mobile di 24 ore. È impostato per portfolio aziendale e condiviso da tutti i suoi numeri. I nuovi portfolio partono da 250. Per arrivare a 2.000, verifica la tua attività oppure invia 2.000 messaggi consegnati al di fuori delle finestre di assistenza a clienti unici entro 30 giorni usando modelli di alta qualità. Dopo, Meta alza automaticamente il limite a 10.000, 100.000 e illimitato quando la qualità resta alta e usi almeno metà del limite attuale in 7 giorni. Controlla il tuo in WhatsApp Manager da Account tools > Messaging limits.

131048, 368 e 131031: invii o account limitati

131048 significa che l'invio dal numero è limitato perché troppi messaggi precedenti sono stati bloccati o segnalati come spam; controlla lo stato della qualità in WhatsApp Manager. I codici 368 e 131031 significano che l'account è stato limitato o disattivato per una violazione delle policy. Leggi l'avviso in Business Support Home e presenta ricorso se ritieni che sia un errore. Il codice 130497 significa che la categoria della tua attività non può scrivere a clienti in alcuni paesi.

Mantieni sano il tuo quality rating

• Scrivi solo ai clienti che hanno ordinato da te o che hanno dato il consenso.
• Invia gli aggiornamenti sugli ordini, come le conferme d'ordine, come modelli Utility e tieni le promozioni nei modelli Marketing.
• Mantieni il marketing pertinente e poco frequente, e rendi facile la disiscrizione.

Coexistence, chiamate, Flows e username

Questi errori provengono dalle funzionalità più recenti di WhatsApp. La maggior parte dei negozi li incontra solo mentre collega il numero di una WhatsApp Business App o testa una funzione che Meta sta ancora distribuendo.

Coexistence: errori di associazione e liste broadcast

La coexistence collega il numero della tua WhatsApp Business App all'API, così puoi continuare a chattare dal telefono mentre Whapi invia le automazioni. Meta disattiva le liste broadcast nell'app una volta che ti colleghi, e le liste esistenti diventano di sola lettura. «Error while pairing Cloud API» e gli altri errori di associazione, la cronologia chat mancante e le disconnessioni sono trattati in la coexistence di WhatsApp non funziona.

«Calling APIs cannot be enabled for this phone number»

L'errore 138015 di Meta significa che le chiamate di WhatsApp Business non possono ancora essere attivate per quel numero. La soluzione di Meta è assicurarsi che il limite di messaggistica del numero sia 2.000 o più. Usa i passaggi sui limiti di messaggistica qui sopra per arrivarci.

WhatsApp Flows: «Blocked By Integrity»

L'errore 139000 significa che Meta ha individuato un problema di integrità sull'account che impedisce di creare o pubblicare un Flow. Controlla in Business Support Home le restrizioni sull'attività, poi contatta l'assistenza di Meta, che è l'unica via indicata da Meta per questo codice.

Business-scoped user ID (BSUID)

WhatsApp sta introducendo username facoltativi, quindi Meta ora identifica i clienti anche con un business-scoped user ID (BSUID) unico per ogni portfolio aziendale. Alcuni tipi di messaggio non possono essere indirizzati a un BSUID, e Meta restituisce 131062, «Business-scoped User ID (BSUID) recipients are not supported for this message.» Inviare al numero di telefono del cliente lo evita. Gli ordini Shopify contengono il numero di telefono, che è quello usato dalle automazioni degli ordini.

Interruzioni di Meta e accesso scaduto

I codici 2, 131016 e 133004 significano che il servizio di Meta è sovraccarico o brevemente non disponibile, quindi la soluzione è aspettare e riprovare. Il codice 1 può essere un errore del server o una richiesta malformata, e il consiglio di Meta per tutti e quattro è controllare prima metastatus.com. 131000 è un errore sconosciuto; riprova una volta e segnalalo se si ripete.

I codici 0 e 190 significano che il token di accesso che permette a Whapi di inviare per il tuo account è scaduto o è stato invalidato. Meta indica come causa anche un'impostazione utente che impedisce a tutte le app di accedere ai propri dati. I codici 10 e da 200 a 299 significano che un'autorizzazione è stata rimossa. In ogni caso, ricollega WhatsApp dalla dashboard di Whapi così Meta emette un nuovo accesso.

Come ottenere aiuto con un errore di WhatsApp API

Invia prima di tutto il codice di errore, perché dice all'assistenza dove guardare. L'assistenza di Whapi risponde via email a info@usewhapi.com e su WhatsApp. Includi:

• il codice di errore e il messaggio di Meta, oppure uno screenshot;
• data e ora in cui è successo, con il tuo fuso orario;
• il numero d'ordine Shopify o l'automazione che è fallita;
• se falliscono tutti i messaggi o solo alcuni clienti.

Per problemi di account, fatturazione o policy che solo Meta può risolvere, apri un ticket in Meta Direct Support. Per i problemi con la carta, Meta chiede di scegliere l'argomento «Dev: Billing, Credit & Pricing» e il tipo di richiesta «Credit Card Billing». Se non vedi quell'argomento, Meta dice di chiedere al tuo provider di aprire il ticket, quindi scrivici e lo apriremo noi. Puoi anche raggiungerci dalla pagina dei contatti.