Genuka WA docs

Error 131049 de WhatsApp: mensaje de marketing no entregado

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

(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):

  • 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). 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:

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?

CanalQué recibes
Webhook message_statusdata.status: "failed", data.errors[0].code: 131049
Campaña, fallo informado por webhookEl destinatario pasa a failed, con el mensaje de Meta en errorMessage
Campaña, rechazo durante la llamadaEl 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 llamada400, "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?

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.

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.

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.

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),
  });
}

¿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: la persona dejó de recibir tus mensajes de marketing; nunca reenvíes.
  • 131048: tu número está restringido por reportes de spam, no un solo destinatario.
  • 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). 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

En esta página