# Errore WhatsApp 131049: messaggio di marketing non consegnato

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

> Errore WhatsApp 131049: Meta ha trattenuto il tuo modello di marketing per mantenere sano il coinvolgimento. Il limite per utente, e quando rinviare senza peggiorare le cose.

L'errore WhatsApp 131049 significa che Meta ha scelto di non consegnare un modello di marketing a questo destinatario,
il più delle volte perché per ora ha raggiunto il suo limite di messaggi di marketing. Non è né un bug né una
penalità sul tuo numero. Aspetta almeno 24 ore prima di riprovare con quel destinatario, a meno che non abbia
un numero statunitense: lì, aspettare non serve.

## Cosa significa l'errore 131049?

> "This message was not delivered to maintain healthy ecosystem engagement."
> — [Meta, Cloud API error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#other-errors)

Meta aggiunge: "If you do receive this error code and suspect it is due to the limit, wait at least 24
hours before resending the template message." Il limite in questione è il **limite per utente dei modelli
di messaggio di marketing**
([Meta, Per-user marketing template message limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits)):

* WhatsApp può limitare quanti modelli di marketing una persona riceve **da qualsiasi azienda** in un
  periodo, quando è meno probabile che interagisca con essi.
* Il limite si adatta a ogni persona: il suo tasso di lettura recente dei messaggi di marketing, e quanti messaggi
  ha già nella sua inbox da amici, familiari e aziende.
* Ogni modello di marketing **consegnato** conta. Se la persona risponde, si apre una finestra di assistenza clienti
  di 24 ore, e i messaggi di marketing inviati dentro quella finestra non contano.
* Rinviare più volte entro 24 ore a qualcuno che ha raggiunto il suo limite può rendere quel
  destinatario irraggiungibile per fino a altre 24 ore, con lo stesso 131049. Gli altri tuoi destinatari
  non ne risentono.
* Il limite non è attivo per i messaggi inviati da un numero dello Spazio economico europeo, del
  Regno Unito, del Giappone o della Corea del Sud, né verso un utente in quei paesi.

### Perché i miei destinatari statunitensi falliscono sempre?

Perché Meta non consegna più alcun modello di marketing a loro. Sulla stessa pagina:

> "WhatsApp does not currently deliver marketing template messages to WhatsApp users with United
> States phone numbers (numbers composed of a +1 dialing code and a US area code)."

Questo **non** è il limite per utente: il blocco non si toglie dopo 24 ore, e Meta non annuncia alcuna
data di fine. Meta parla solo di "an error", senza codice; gli integratori lo riportano come 131049, in vigore
dal 1° aprile 2025
([Message Central](https://www.messagecentral.com/blog/whatsapp-marketing-usa-allowed)). Sono coinvolti solo i
prefissi statunitensi, non tutti i numeri +1.

* **Togli quei numeri dalle tue campagne `MARKETING`.** In una campagna, un 131049 ricevuto alla
  chiamata lascia il destinatario `pending`: un numero statunitense resterà lì a ogni rilancio.
* **Usa un altro tipo di messaggio**: un modello `UTILITY` o `AUTHENTICATION` quando il contenuto lo consente
  (queste categorie non sono coinvolte, secondo la stessa fonte), oppure una risposta dentro la finestra di
  servizio di 24 ore che apre un messaggio del cliente.
* **Non riprogrammarli ogni 24 ore**: ogni invio che Meta accetta prima di farlo fallire conta
  sulla quota del tuo abbonamento Genuka WA.

## Quando si verifica l'errore 131049?

Riguarda solo i modelli `MARKETING`, e arriva sul webhook di stato: Meta lo dice
esplicitamente, il fallimento è segnalato dal webhook `messages` con lo stato `failed`. Ecco
l'esempio di Meta stessa, così come Genuka WA te lo inoltra in `data`:

```json title="message_status webhook (excerpt)"
{
  "type": "message_status",
  "field": "messages",
  "data": {
    "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
    "status": "failed",
    "timestamp": "1751142888",
    "recipient_id": "16505551234",
    "errors": [
      {
        "code": 131049,
        "title": "This message was not delivered to maintain healthy ecosystem engagement.",
        "message": "This message was not delivered to maintain healthy ecosystem engagement.",
        "error_data": {
          "details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
        },
        "href": "/documentation/business-messaging/whatsapp/support/error-codes"
      }
    ]
  }
}
```

### Dove lo vedi in Genuka WA?

| Canale                                                                     | Cosa ottieni                                                                                   |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Webhook `message_status`                                                   | `data.status: "failed"`, `data.errors[0].code: 131049`                                         |
| Campagna, fallimento segnalato via webhook                                 | Il destinatario diventa `failed`, con il messaggio di Meta in `errorMessage`                   |
| Campagna, rifiutato alla chiamata                                          | Il destinatario resta `pending`: non viene contato come fallito, e un nuovo lancio lo riprende |
| Risposta di `POST /api/v1/messages`, quando Meta rifiuta già alla chiamata | `400`, `"error": "send_recipient_throttled"`, `meta.code: 131049`                              |

Genuka WA classifica questo codice come `recipient_throttled`: il messaggio va bene, il destinatario va
bene, è il momento a essere sbagliato. Non viene mai riprovato subito, perché servirebbe solo a prolungare il
blocco.

## Come risolvo l'errore 131049?

1. **Non inviare nulla per 24 ore.** È l'unica istruzione di Meta, e quella più spesso ignorata: un
   rinvio immediato non passa e può prolungare il blocco.
2. **Metti da parte quei destinatari.** Dal webhook, salva il numero e l'ora del fallimento.
   `GET /api/v1/campaigns/{id}/recipients?status=failed&limit=1000` ti dà anche l'elenco lato
   campagna, limitato a 1.000 righe senza paginazione: oltre, affidati a quello che hai salvato dal
   webhook.
3. **Riprovali più tardi, in una nuova campagna**, almeno 24 ore dopo il fallimento, senza i numeri
   statunitensi. Una campagna già lanciata rinvia solo i destinatari ancora
   `pending`.

**Node.js**

```ts
import { parsePhoneNumberFromString } from "libphonenumber-js";

const RETRY_AFTER_MS = 24 * 60 * 60 * 1000;

// Called by your webhook route, once the signature is verified.
export async function onMessageStatus(event: {
  type: string;
  data: { status: string; recipient_id: string; errors?: { code: number }[] };
}) {
  if (event.type !== "message_status" || event.data.status !== "failed") return;
  if (!event.data.errors?.some((error) => error.code === 131049)) return;

  // A US number will not receive marketing in 24 hours either: take it out of your campaigns.
  if (parsePhoneNumberFromString(`+${event.data.recipient_id}`)?.country === "US") {
    await db.marketingExclusion.upsert({ waId: event.data.recipient_id, reason: "us_marketing" });
    return;
  }

  // Your storage: a "retry later" table with the earliest time a resend is allowed.
  await db.marketingRetry.upsert({
    waId: event.data.recipient_id,
    notBefore: new Date(Date.now() + RETRY_AFTER_MS),
  });
}
```

**Python**

```python
from datetime import datetime, timedelta, timezone

import phonenumbers

RETRY_AFTER = timedelta(hours=24)


# Called by your webhook route, once the signature is verified.
def on_message_status(event: dict) -> None:
    data = event.get("data", {})
    if event.get("type") != "message_status" or data.get("status") != "failed":
        return
    if not any(error.get("code") == 131049 for error in data.get("errors", [])):
        return

    # A US number will not receive marketing in 24 hours either: take it out of your campaigns.
    number = phonenumbers.parse("+" + data["recipient_id"])
    if phonenumbers.region_code_for_number(number) == "US":
        exclude_from_marketing(data["recipient_id"])  # your function
        return

    # Your storage: a "retry later" table with the earliest time a resend is allowed.
    save_marketing_retry(
        wa_id=data["recipient_id"],
        not_before=datetime.now(timezone.utc) + RETRY_AFTER,
    )
```

## Come prevengo l'errore 131049?

* **Punta su chi legge.** Il limite segue il tasso di lettura recente di ogni destinatario: una lista di
  clienti attivi rende meglio di tutta la tua anagrafica.
* **Invita a rispondere.** Una risposta apre una finestra di 24 ore in cui i tuoi messaggi di marketing non contano
  più sul limite.
* **Distanzia le campagne** verso le stesse persone, e togli dalle tue liste chi continua a collezionare
  131049\.
* **Misura la consegna sui webhook**, non sugli invii accettati: una campagna di marketing può mostrare il 100%
  di accettati e una quota di 131049 all'arrivo.

## Codici di errore correlati

* [131050](https://wa.genuka.com/it/docs/errors/131050): la persona ha interrotto i tuoi messaggi di marketing; non rinviare mai.
* [131048](https://wa.genuka.com/it/docs/errors/131048): è **il tuo numero** a essere limitato a causa di segnalazioni di spam, non un
  singolo destinatario.
* [131026](https://wa.genuka.com/it/docs/errors/131026): il destinatario non può ricevere proprio nulla.

## FAQ

### L'errore 131049 penalizza il mio numero?

No. Meta precisa che il blocco causato da rinvii eccessivi non incide sulla tua capacità di inviare
messaggi di marketing ad altri utenti. È un limite per destinatario.

### I modelli di utilità e di autenticazione sono coinvolti?

Il limite descritto da Meta si applica ai modelli di marketing. Un codice di accesso o una conferma d'ordine in
un modello `AUTHENTICATION` o `UTILITY` non vi è soggetto.

### Quanto dura il limite?

Meta non indica una durata fissa: il limite si adatta al coinvolgimento di ogni persona. La regola è non
rinviare prima di almeno 24 ore.

### Perché alcuni dei miei destinatari europei non ricevono mai 131049?

Perché il limite non è attivo per gli utenti dello Spazio economico europeo, del Regno Unito,
del Giappone e della Corea del Sud, né per i messaggi inviati da un numero in quei paesi.

### Un modello di marketing fallito con 131049 viene fatturato?

Non da Meta, che addebita un modello di messaggio solo quando viene consegnato
([Meta, Pricing](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)).
Lato Genuka WA, l'invio accettato da Meta ha già contato sulla quota del tuo
abbonamento: rinviare troppo presto costa un messaggio di quota e non consegna nulla.

## Fonti

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Per-user marketing template message limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits)
* [Meta — Status webhook reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)
* [Meta — Pricing](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)
* [Message Central — WhatsApp marketing in the USA](https://www.messagecentral.com/blog/whatsapp-marketing-usa-allowed)
