Por qué falló un mensaje de WhatsApp: cómo leer el estado failed y sus errores
Un webhook de estado failed indica que Meta no pudo enviar ni entregar un mensaje que la empresa envió por la API. Llega en el campo messages con status failed y un array errors con code, title, message, error_data.details y href. El código indica el motivo: 131047 ventana cerrada, 131026 no entregable, 131049 límite de marketing, 131050 marketing detenido, 131042 problema de pago.
easyCoexistence conecta el número de tu app de WhatsApp Business con la Cloud API de Meta mediante Coexistencia y pasa los estados failed a tu servidor, directamente o como reenvíos firmados cuando las automatizaciones están activas.
Han pasado más de 24 horas desde la última respuesta del destinatario; la solución de Meta es enviar una plantilla en su lugar.
No se entregó para mantener un buen nivel de interacción en el ecosistema; espera al menos 24 horas antes de volver a enviar la plantilla de marketing.
El destinatario eligió dejar de recibir mensajes de marketing de la empresa; Meta indica que no se reintente.
Un estado failed no incluye el array contacts, así que relaciona el fallo con el envío mediante statuses.id.
Lo que Meta cobra: los mensajes se facturan cuando se entregan, no cuando se envían.
¿Cómo es un estado failed?
Igual que cualquier otro estado, más errors. Falta el array contacts, se omite recipient_user_id cuando el mensaje se envió a un número de teléfono y no hay objeto pricing. title y message llevan el mismo texto, error_data.details lo explica en una frase y href apunta a la lista de códigos de error de Meta. Este es el ejemplo de la propia Meta, una plantilla de marketing frenada por el límite por usuario:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"statuses": [
{
"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"
}
]
}
]
},
"field": "messages"
}
]
}
]
}¿Qué códigos de error aparecen con más frecuencia y qué significan?
Meta devuelve los errores en la respuesta del envío, en un estado failed o en ambos, así que el mismo código puede llegarte por cualquiera de las dos vías y tu handler debe leer las dos. Estos son los códigos que explican la mayoría de los mensajes que nunca llegan, con el motivo que da Meta y lo primero que conviene probar; la lista completa está en la referencia de códigos de error de Meta:
¿Cómo debe reaccionar un handler ante cada tipo de fallo?
Clasifica el código según lo que toca hacer antes de que se reintente nada. Reintentarlo todo por igual convierte una baja de marketing en fallos repetidos y puede alargar un bloqueo, mientras que descartar un error temporal hace perder un mensaje que habría salido un minuto después.
- Reintentar con backoff: 131000 desconocido, 131016 servicio no disponible, 130429 throughput alcanzado.
- Esperar primero: 131049, al menos 24 horas, porque los reintentos tempranos pueden bloquear a ese usuario hasta 24 horas más.
- Cambiar el mensaje: 131047 requiere una plantilla aprobada, porque la ventana de 24 horas está cerrada.
- Dejar de enviar a este cliente: 131050, hasta que llegue un resume en
user_preferences. - Corregir la cuenta o el contenido: 131042 pago, 131031 cuenta restringida, 131053 multimedia.
¿Qué fallos aparecen solo como estado failed?
Los que Meta decide después de aceptar la petición. El envío devuelve un wamid y el rechazo llega más tarde por este webhook. Meta no entrega plantillas de marketing a usuarios de WhatsApp con números de teléfono de Estados Unidos (+1 con un código de área de EE. UU.), una plantilla de marketing enviada a un cliente que dejó de recibir mensajes de marketing se procesa y luego se reporta como failed con 131050, y el límite de marketing por usuario reporta 131049 de la misma forma.
Si el número no tiene destino de webhook, estos fallos no quedan en ningún sitio visible y el mensaje simplemente parece enviado. Para el orden completo de comprobaciones cuando un cliente no recibió nada, consulta la página sobre mensajes de la API de WhatsApp que no se entregan.
¿Qué cambia en un número con Coexistencia?
Hay dos cosas importantes. Primero, la ventana de 24 horas solo afecta a la API. La guía de Coexistencia de Meta indica que los mensajes enviados desde la app de WhatsApp Business no están sujetos a la ventana de atención al cliente, así que tras un 131047 el propietario aún puede responder a ese cliente desde el teléfono mientras tu sistema envía una plantilla aprobada.
Segundo, el throughput es fijo. Un número que se usa a la vez en la app y en la API envía como máximo 20 mensajes por segundo, y si se supera ese límite se devuelve 130429. Todo lo demás se lee igual que en cualquier número de Cloud API: mismo campo, mismo array errors, mismos códigos.
¿Cómo ven los fallos las automatizaciones y tu IA?
Depende de cuándo lo rechace Meta. Un rechazo en el momento del envío, como 131047, hace fallar el paso de la automatización: la ejecución aparece como Failed con el mensaje de Meta en la pestaña Runs, y el propietario recibe un correo para que pueda responder él mismo a ese cliente. Además, las automatizaciones comprueban la ventana antes de enviar una respuesta de texto libre y, si está cerrada, omiten el envío con window_closed en lugar de intentarlo.
Un fallo que Meta reporta después llega como estado failed a tu Forward URL o a tu destino directo, y la ejecución queda como estaba. Una IA que envió una plantilla por el conector MCP ve el wamid y "sent: true"; consulta en tu sistema el estado de ese wamid, o pide al asistente que ejecute get_number_health cuando fallen muchos mensajes a la vez.
Errores comunes
- Reintentar 131050 en bucle. El cliente dejó de recibir mensajes de marketing, así que cada intento falla igual hasta que vuelva a activarlos.
- Reenviar a las pocas horas una plantilla de marketing que dio 131049. Meta pide esperar al menos 24 horas, y los reintentos tempranos pueden bloquear a ese usuario hasta 24 horas más.
- Registrar solo el title. error_data.details contiene el motivo concreto, así que guarda code y details junto con el wamid.
- Operar sin destino de webhook y juzgar la entrega por la respuesta del envío, que solo indica que Meta aceptó el mensaje.
Cuando Meta rechaza la respuesta de una automatización en el momento del envío, la ejecución muestra el error de Meta y recibes un correo, y cada número se monitoriza 24/7 para detectar desconexiones y caídas de calidad. De US$ 9 a US$ 0.75 por número al mes, un precio que baja a medida que añades números, con los primeros 3 días gratis.
Preguntas frecuentes
¿Meta cobra por un mensaje de WhatsApp que falla?
Las páginas de precios de Meta indican que cobra por los mensajes entregados, no por los que solo se envían. Un estado failed no incluye objeto pricing. Los cargos van a la propia WhatsApp Business Account de la empresa; easyCoexistence nunca les añade margen.
¿El error 131026 significa que el cliente bloqueó a la empresa?
La lista de Meta para 131026 menciona otros motivos: el número no está en WhatsApp, el destinatario no ha aceptado las condiciones más recientes o su versión de WhatsApp es demasiado antigua. Meta sugiere pedir al cliente por otro canal que compruebe esos puntos.
¿Por qué recipient_user_id aparece en algunos fallos y en otros no?
Meta lo omite en un estado failed cuando el mensaje se envió a un número de teléfono. Si enviaste al BSUID del cliente, el fallo lo incluye y puede que el que falte sea recipient_id.
¿Puede fallar un mensaje después de haberse entregado?
La referencia de Meta define failed como un fallo al enviar o entregar. Una vez que el mensaje llegó al dispositivo, los siguientes estados que cabe esperar son read, o played en los mensajes de voz.
Sigue leyendo
¿Listo para empezar?
Configura WhatsApp Coexistence en minutos, no en meses. La app sigue funcionando en el teléfono.
Empezar prueba gratisVerificado el