Genuka WA docs

Codici di errore della WhatsApp Cloud API: cause e soluzioni

I codici di errore della WhatsApp Cloud API spiegati: cosa significano 131047, 131026, 130429, 132001, 141010 e gli altri, e se conviene riprovare.

Un codice di errore WhatsApp è il numero che Meta restituisce quando la Cloud API rifiuta una chiamata o non riesce a consegnare un messaggio. Con Genuka WA lo leggi nel campo meta.code della risposta di errore, oppure in data.errors[].code del webhook di stato failed. Le tabelle qui sotto indicano, per ogni codice, cosa significa e se conviene riprovare.

Ultimo aggiornamento: 8 ottobre 2026

Quali codici di errore WhatsApp sono documentati qui?

Le famiglie seguono l'elenco ufficiale di Meta (autorizzazione, limitazione, integrità, altri errori), con gli "altri errori" raggruppati qui per argomento. I messaggi di Meta sono citati testualmente, in inglese, così come arrivano nelle risposte dell'API.

Autorizzazione e token di accesso

CodiceMessaggio di MetaCosa significaRiprovare?
0"We were unable to authenticate the app user."Il token di accesso è scaduto, è stato invalidato oppure il suo proprietario ha revocato l'accesso all'app.No: serve un nuovo token. Con Genuka WA quel token è nostro: contatta il supporto.
3"Capability or permissions issue."All'app manca la capacità o l'autorizzazione richiesta da questo specifico endpoint.No: concedi l'autorizzazione mancante.
10"Permission is either not granted or has been removed."Manca un'autorizzazione. Caso frequente: un modello OTP per un'azienda che Meta non ha verificato.No.
190"Your access token has expired."Il token di accesso è scaduto o non è più valido.No: sostituisci il token. Con Genuka WA non gestisci mai un token Meta.
200"Permission is either not granted or has been removed." (intervallo da 200 a 299)Token mancante, autorizzazione revocata o un utente di sistema senza accesso all'account. Non ha nulla a che vedere con lo stato HTTP 200.No: ripristina l'accesso.

Limitazione

CodiceMessaggio di MetaCosa significaRiprovare?
4"The app has reached its API call rate limit."L'intera app ha superato il suo limite di chiamate all'API di Meta.Sì, più tardi, con meno chiamate.
80007"The WhatsApp Business Account has reached its rate limit."Troppe chiamate di gestione (modelli, numeri) su uno stesso account WhatsApp Business nell'arco di un'ora.Sì, più tardi.
130429"Cloud API message throughput has been reached."Il numero invia più velocemente del suo throughput di messaggi.Sì, con attese crescenti.
131048"Message failed to send because there are restrictions on how many messages can be sent from this phone number…"Meta limita gli invii del numero dopo troppi blocchi o segnalazioni di spam.Solo più tardi, dopo aver ripulito i tuoi invii.
131056"Too many messages sent from the sender phone number to the same recipient phone number in a short period of time."Troppi messaggi allo stesso destinatario in poco tempo.Sì, verso quel destinatario, dopo una pausa.

Integrità e salute dell'account

CodiceMessaggio di MetaCosa significaRiprovare?
368"The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy."L'account WhatsApp Business è limitato o disattivato per aver violato una policy di Meta.No: chiedi una revisione a Meta.
141010"The Business has not passed business verification"L'azienda non ha superato la verifica di Meta, quindi i suoi modelli OTP vengono rifiutati. Questo codice compare nello stato di salute dell'account (health_status), non nell'elenco dei codici di errore di Meta.No: fai verificare l'azienda.

Richiesta e numero di telefono

CodiceMessaggio di MetaCosa significaRiprovare?
33"The business phone number has been deleted."L'ID del numero di telefono che usi non punta più a un numero attivo.No: controlla l'ID, ricollega il numero.
100"The request included one or more unsupported or misspelled parameters."Un parametro è sconosciuto, scritto male o troppo lungo. La causa si trova di solito in details.No: correggi la richiesta.

Consegna e pagamento

CodiceMessaggio di MetaCosa significaRiprovare?
131026"Unable to deliver message. Reasons can include: The recipient phone number is not a WhatsApp phone number…"Il destinatario non è su WhatsApp, non ha accettato i termini o usa una versione dell'app troppo vecchia.No: controlla il numero, usa un altro canale.
131042"There was an error related to your payment method."L'account WhatsApp Business non ha un metodo di pagamento valido presso Meta, che fattura direttamente il cliente.Una volta aggiunto o corretto il metodo di pagamento presso Meta.
131047"More than 24 hours have passed since the recipient last replied to the sender number."La finestra di 24 ore del servizio clienti è chiusa: può partire solo un modello approvato.No: invia di nuovo il contenuto come modello.
131049"This message was not delivered to maintain healthy ecosystem engagement."Meta ha trattenuto un modello di marketing, molto spesso perché il destinatario ha raggiunto il suo limite di messaggi di marketing.Non prima di 24 ore (i numeri statunitensi sono un caso a parte, vedi la pagina).
131050"Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business."Il destinatario ha interrotto i tuoi messaggi di marketing.Mai.

Modelli e Flows

CodiceMessaggio di MetaCosa significaRiprovare?
132000"The number of variable parameter values included in the request did not match the number of variable parameters defined in the template."Il numero di valori inviati non corrisponde alle variabili del modello.No: invia un valore per ogni variabile.
132001"The template does not exist in the specified language or the template has not been approved."Nessun modello approvato con quel nome in quella lingua. Trappola frequente: en e en_US sono due modelli diversi.No: controlla nome, lingua e stato.
132015"Template is paused due to low quality so it cannot be sent in a template message."Meta ha messo in pausa il modello per qualità bassa.Quando la pausa termina, oppure con un altro modello.
132069"Flow is in throttled state and 10 messages using this flow were already sent in the last hour."Il Flow è limitato a 10 invii all'ora perché il suo endpoint non è in salute.Una volta sistemato l'endpoint.

Dove trovo il codice di errore in Genuka WA?

In due punti, a seconda di quando Meta rifiuta.

Durante la chiamata. Quando Meta rifiuta la richiesta, la risposta di errore di Genuka WA contiene un oggetto meta: il codice di Meta, la sua classe, retryable che dice se ha senso un nuovo tentativo, e traceId, l'identificativo che chiede il supporto Meta. Esempio dal riferimento API:

422 — rifiutato da Meta
{
  "error": "meta_rejected",
  "message": "Invalid parameter",
  "meta": {
    "errorClass": "template",
    "retryable": false,
    "code": 100,
    "details": "body_text example count does not match the number of variables",
    "traceId": "AbC…"
  }
}

Dopo l'invio. Un messaggio accettato può comunque non essere consegnato (131026, 131049, 131050…). Il fallimento arriva allora ai tuoi webhook: un evento message_status, stato failed, con il codice di Meta in data.errors:

Webhook message_status (estratto)
{
  "type": "message_status",
  "field": "messages",
  "connection_id": "con_1",
  "data": {
    "id": "wamid.HBgLMjM3...",
    "status": "failed",
    "recipient_id": "237690000001",
    "errors": [{ "code": 131026, "title": "…", "message": "…" }]
  }
}

Il mio codice non è in questo elenco: dove cerco?

Meta pubblica l'elenco completo dei codici della Cloud API, con la soluzione suggerita per ciascuno: Cloud API error codes. Il campo meta.details riporta il dettaglio fornito da Meta per la tua richiesta. Se il rifiuto continua a non avere senso, invia al supporto il meta.traceId e l'header x-request-id della risposta.

FAQ

Qual è la differenza tra gli errori 4, 80007 e 130429?

Non limitano la stessa cosa. L'errore 4 limita le chiamate dell'intera app, 80007 le chiamate di gestione su un account WhatsApp Business (modelli, numeri) e 130429 il throughput di messaggi di un numero. Tutti e tre si riprovano più tardi, con attese crescenti.

Devo riprovare automaticamente gli errori WhatsApp?

Solo quando meta.retryable è true, e con attese crescenti. Gli errori di autorizzazione, di modello e di destinatario falliscono allo stesso modo finché la loro causa non viene risolta. Un caso particolare: 131048 è segnato come ritentabile, ma significa "più tardi", non "subito".

Perché "Application does not have permission for this action" su un modello OTP?

Perché l'azienda non ha superato la verifica di Meta: i suoi modelli di autenticazione vengono rifiutati e lo stato di salute dell'account riporta l'errore 141010. Il messaggio dà la colpa all'app per errore. Vedi anche l'errore 10.

L'errore 131047 significa che il mio numero è bloccato?

No. Significa solo che il contatto non ti scrive da più di 24 ore. Invia di nuovo il contenuto come modello approvato; la conversazione libera riprende non appena risponde.

Fonti

Consultate l'8 ottobre 2026.

In questa pagina