# Codici di errore della WhatsApp Cloud API: cause e soluzioni

URL: https://wa.genuka.com/it/docs/errors
Language: Italian

> 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
(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

| Codice                     | Messaggio di Meta                                                                 | Cosa significa                                                                                                                             | Riprovare?                                                                         |
| -------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| [0](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/3)     | "Capability or permissions issue."                                                | All'app manca la capacità o l'autorizzazione richiesta da questo specifico endpoint.                                                       | No: concedi l'autorizzazione mancante.                                             |
| [10](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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

| Codice                           | Messaggio di Meta                                                                                                   | Cosa significa                                                                                             | Riprovare?                                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [4](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/130429) | "Cloud API message throughput has been reached."                                                                    | Il numero invia più velocemente del suo throughput di messaggi.                                            | Sì, con attese crescenti.                        |
| [131048](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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

| Codice                           | Messaggio di Meta                                                                                                        | Cosa significa                                                                                                                                                                                                        | Riprovare?                       |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| [368](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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

| Codice                     | Messaggio di Meta                                                        | Cosa significa                                                                                     | Riprovare?                               |
| -------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| [33](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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

| Codice                           | Messaggio di Meta                                                                                                               | Cosa significa                                                                                                                       | Riprovare?                                                                        |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| [131026](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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

| Codice                           | Messaggio di Meta                                                                                                                          | Cosa significa                                                                                                        | Riprovare?                                            |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [132000](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/api):

```json title="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](https://wa.genuka.com/it/docs/webhooks): un evento
`message_status`, stato `failed`, con il codice di Meta in `data.errors`:

```json title="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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/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](https://wa.genuka.com/it/docs/errors/4) limita le chiamate dell'intera app,
[80007](https://wa.genuka.com/it/docs/errors/80007) le chiamate di gestione su un account WhatsApp Business (modelli,
numeri) e [130429](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/141010). Il
messaggio dà la colpa all'app per errore. Vedi anche [l'errore 10](https://wa.genuka.com/it/docs/errors/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.

* Meta — [Error codes (Cloud API)](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* Meta — [Health status](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/health-status)
