# Error 131049 de WhatsApp: mensaje de marketing no entregado

URL: https://wa.genuka.com/es/docs/errors/131049
Language: Spanish

> Error 131049 de WhatsApp: Meta retuvo tu plantilla de marketing para mantener un buen nivel de interacción. El límite por usuario, y cuándo reenviar sin empeorar la situación.

El error 131049 de WhatsApp significa que Meta decidió no entregar una plantilla de marketing a
este destinatario, casi siempre porque alcanzó por ahora su límite de mensajes de marketing. No es
un fallo ni una sanción contra tu número. Espera al menos 24 horas antes de volver a intentarlo
con ese destinatario, salvo que tenga un número de EE. UU.: en ese caso, esperar no sirve de nada.

## ¿Qué significa el error 131049?

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

(Este mensaje no se entregó para mantener un nivel saludable de interacción en el ecosistema).

Meta agrega: "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." (Si recibes este código de error y sospechas que
se debe al límite, espera al menos 24 horas antes de reenviar el mensaje de plantilla). El límite
en cuestión es el **límite por usuario de mensajes de plantilla de marketing**
([Meta, Per-user marketing template message limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits)):

* WhatsApp puede limitar cuántas plantillas de marketing recibe una persona **de cualquier
  empresa** durante un periodo, cuando es menos probable que interactúe con ellas.
* El límite se adapta a cada persona: su tasa reciente de lectura de mensajes de marketing y la
  cantidad de mensajes que ya tiene en su bandeja de amigos, familiares y empresas.
* Cada plantilla de marketing **entregada** cuenta. Si la persona responde, se abre una ventana de
  24 horas de atención al cliente, y los mensajes de marketing enviados dentro de esa ventana no
  cuentan.
* Reenviar varias veces en 24 horas a alguien que alcanzó su límite puede dejar a ese destinatario
  inalcanzable hasta 24 horas más, con el mismo 131049. Tus demás destinatarios no se ven
  afectados.
* El límite no está activo para los mensajes enviados desde un número del Espacio Económico
  Europeo, el Reino Unido, Japón o Corea del Sur, ni para un usuario de esos países.

### ¿Por qué siempre fallan mis destinatarios de EE. UU.?

Porque Meta ya no les entrega ninguna plantilla de marketing. En la misma página:

> "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)."

(Actualmente WhatsApp no entrega mensajes de plantilla de marketing a usuarios de WhatsApp con
números de teléfono de Estados Unidos, es decir, números compuestos por el prefijo +1 y un código
de área de EE. UU.).

Esto **no** es el límite por usuario: el bloqueo no se levanta después de 24 horas, y Meta no
anuncia ninguna fecha de fin. Meta solo habla de "an error", sin código; los integradores lo
reportan como 131049, vigente desde el 1 de abril de 2025
([Message Central](https://www.messagecentral.com/blog/whatsapp-marketing-usa-allowed)). Solo
afecta a los códigos de área de EE. UU., no a todos los números +1.

* **Quita esos números de tus campañas `MARKETING`.** En una campaña, un 131049 recibido durante
  la llamada deja al destinatario en `pending`: un número de EE. UU. se quedará ahí en cada
  relanzamiento.
* **Usa otro tipo de mensaje**: una plantilla `UTILITY` o `AUTHENTICATION` cuando el contenido lo
  permita (esas categorías no se ven afectadas, según la misma fuente), o una respuesta dentro de
  la ventana de 24 horas que abre un mensaje del cliente.
* **No los reprogrames cada 24 horas**: cada envío que Meta acepta antes de hacerlo fallar cuenta
  contra la cuota de tu suscripción a Genuka WA.

## ¿Cuándo aparece el error 131049?

Solo afecta a las plantillas `MARKETING`, y llega por el webhook de estado: Meta lo dice
explícitamente, el fallo se informa en el webhook `messages` con el estado `failed`. Este es el
propio ejemplo de Meta, tal como Genuka WA te lo reenvía en `data`:

```json title="Webhook message_status (extracto)"
{
  "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"
      }
    ]
  }
}
```

### ¿Dónde lo ves en Genuka WA?

| Canal                                                                        | Qué recibes                                                                                        |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Webhook `message_status`                                                     | `data.status: "failed"`, `data.errors[0].code: 131049`                                             |
| Campaña, fallo informado por webhook                                         | El destinatario pasa a `failed`, con el mensaje de Meta en `errorMessage`                          |
| Campaña, rechazo durante la llamada                                          | El destinatario se queda en `pending`: no se cuenta como fallido, y un nuevo lanzamiento lo retoma |
| Respuesta de `POST /api/v1/messages`, cuando Meta rechaza durante la llamada | `400`, `"error": "send_recipient_throttled"`, `meta.code: 131049`                                  |

Genuka WA clasifica este código como `recipient_throttled`: el mensaje está bien, el destinatario
está bien, el momento no. Nunca se reintenta de inmediato, porque eso solo prolongaría el
bloqueo.

## ¿Cómo corrijo el error 131049?

1. **No envíes nada durante 24 horas.** Es la única instrucción de Meta, y la que más se ignora: un
   reenvío inmediato no pasa y puede prolongar el bloqueo.
2. **Aparta a esos destinatarios.** Desde el webhook, guarda el número y la hora del fallo.
   `GET /api/v1/campaigns/{id}/recipients?status=failed&limit=1000` también te da la lista del lado de
   la campaña, limitada a 1.000 filas y sin paginación: más allá, apóyate en lo que guardaste desde el
   webhook.
3. **Vuelve a intentarlo más tarde, en una nueva campaña**, al menos 24 horas después del fallo, sin
   los números de EE. UU. Una campaña ya lanzada solo reenvía a sus destinatarios que siguen en
   `pending`.

**Node.js**

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

const RETRY_AFTER_MS = 24 * 60 * 60 * 1000;

// Lo llama tu ruta de webhook, una vez verificada la firma.
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;

  // Un número de EE. UU. tampoco recibirá marketing dentro de 24 horas: sácalo de tus campañas.
  if (parsePhoneNumberFromString(`+${event.data.recipient_id}`)?.country === "US") {
    await db.marketingExclusion.upsert({ waId: event.data.recipient_id, reason: "us_marketing" });
    return;
  }

  // Tu almacenamiento: una tabla de "reintentar más tarde" con la hora mínima en que se permite reenviar.
  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)


# Lo llama tu ruta de webhook, una vez verificada la firma.
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

    # Un número de EE. UU. tampoco recibirá marketing dentro de 24 horas: sácalo de tus campañas.
    number = phonenumbers.parse("+" + data["recipient_id"])
    if phonenumbers.region_code_for_number(number) == "US":
        exclude_from_marketing(data["recipient_id"])  # tu función
        return

    # Tu almacenamiento: una tabla de "reintentar más tarde" con la hora mínima en que se permite reenviar.
    save_marketing_retry(
        wa_id=data["recipient_id"],
        not_before=datetime.now(timezone.utc) + RETRY_AFTER,
    )
```

## ¿Cómo evito el error 131049?

* **Dirígete a quienes leen.** El límite sigue la tasa de lectura reciente de cada destinatario:
  una lista de clientes activos funciona mejor que toda tu base.
* **Invita a responder.** Una respuesta abre una ventana de 24 horas en la que tus mensajes de
  marketing ya no cuentan contra el límite.
* **Espacia las campañas** a las mismas personas, y quita de tus listas a quienes acumulan 131049
  una y otra vez.
* **Mide la entrega con los webhooks**, no con los envíos aceptados: una campaña de marketing puede
  mostrar un 100 % de aceptación y una parte de 131049 a la llegada.

## Códigos de error relacionados

* [131050](https://wa.genuka.com/es/docs/errors/131050): la persona dejó de recibir tus mensajes de marketing; nunca
  reenvíes.
* [131048](https://wa.genuka.com/es/docs/errors/131048): **tu número** está restringido por reportes de spam, no un solo
  destinatario.
* [131026](https://wa.genuka.com/es/docs/errors/131026): el destinatario no puede recibir absolutamente nada.

## Preguntas frecuentes

### ¿El error 131049 penaliza mi número?

No. Meta indica que el bloqueo causado por reenvíos excesivos no afecta tu capacidad de enviar
mensajes de marketing a otros usuarios. Es un límite por destinatario.

### ¿Se ven afectadas las plantillas de utilidad y de autenticación?

El límite que describe Meta se aplica a las plantillas de marketing. Un código de inicio de sesión
o una confirmación de pedido en una plantilla `AUTHENTICATION` o `UTILITY` no está sujeto a él.

### ¿Cuánto dura el límite?

Meta no da una duración fija: el límite se adapta a la interacción de cada persona. La regla es no
reenviar antes de que pasen al menos 24 horas.

### ¿Por qué algunos de mis destinatarios europeos nunca reciben 131049?

Porque el límite no está activo para los usuarios del Espacio Económico Europeo, el Reino Unido,
Japón y Corea del Sur, ni para los mensajes enviados desde un número de esos países.

### ¿Se cobra una plantilla de marketing que falló con 131049?

Meta no la cobra, ya que solo cobra un mensaje de plantilla cuando se entrega
([Meta, Pricing](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)).
Del lado de Genuka WA, el envío que Meta aceptó ya contó contra la cuota de tu suscripción:
reenviar demasiado pronto consume un mensaje de cuota y no entrega nada.

## Fuentes

* [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)
