Códigos de error de WhatsApp Cloud API: significado y solución

Esta guía está pensada para desarrolladores y equipos de operaciones de mensajería que ven mensajes de WhatsApp fallidos y necesitan saber con rapidez si deben corregir la solicitud, esperar, cambiar el tipo de mensaje o parar. Todos los códigos siguientes se han contrastado con la referencia de códigos de error de Cloud API de Meta; los códigos y su redacción cambian, así que confírmelos en esa página antes de fijar lógica en su código.

¿Dónde aparecen los errores de WhatsApp Cloud API?

Los errores aparecen en dos lugares y debe capturar ambos. Los errores de solicitud llegan de inmediato en la respuesta de la API; los de entrega llegan más tarde en un webhook de estado.

• Errores síncronos. La solicitud de envío se rechaza y la respuesta contiene un objeto error con code, message, type y, a menudo, error_data.details. Ejemplos típicos: tokens caducados, parámetros que faltan y desajustes con la plantilla.
• Errores asíncronos. La solicitud de envío tiene éxito y devuelve un ID de mensaje, pero un webhook posterior informa status: failed con un array errors. Ejemplos típicos: ventanas de atención cerradas, destinatarios no alcanzables y límites de marketing.

Un error habitual es registrar solo la respuesta HTTP. El equipo cree entonces que una campaña ha salido bien porque cada solicitud devolvió un ID de mensaje, mientras que cientos de mensajes han fallado en los webhooks. Para entender cómo se relacionan los estados, consulte enviado, entregado, leído y fallido explicados.

¿Cuáles son los códigos de error de WhatsApp más comunes?

La tabla recoge los códigos que encuentran la mayoría de los equipos, agrupados según lo que debe hacer a continuación. Las descripciones parafrasean la referencia de Meta.

¿Cómo se solucionan los errores que causan la mayoría de las campañas fallidas?

En la práctica, un puñado de códigos provoca casi todos los fallos. Cada uno tiene una regla de decisión clara.

131047: la ventana de atención está cerrada

El cliente escribió por última vez hace más de 24 horas. El texto libre, los archivos multimedia y los mensajes interactivos solo se permiten dentro de la ventana de atención al cliente de 24 horas; fuera de ella hay que usar una plantilla aprobada; consulte la ventana de atención al cliente de 24 horas. Los agentes se topan con esto a menudo al responder a un chat antiguo. Muéstreles el estado de la ventana y ofrezca un selector de plantillas cuando haya caducado.

131026: mensaje no entregable

Empiece por la higiene de los números: formato internacional, prefijo de país correcto y sin cero inicial tras el prefijo. Después asuma que algunos números sencillamente no están en WhatsApp o tienen una versión antigua de la aplicación. En mensajes urgentes, como los OTP, recurra al SMS. Consulte WhatsApp, SMS y RCS.

131049 y 131050: límites de marketing y bajas

Ambos afectan a los mensajes de marketing. 131050 es la decisión explícita del usuario de dejar de recibirlos; excluya a esos usuarios del marketing y suscríbase al webhook de preferencias de usuario de Meta. 131049 significa que Meta decidió no entregar para proteger la interacción de los usuarios; Meta aconseja esperar al menos 24 horas, y los reintentos más tempranos probablemente fallarán de nuevo. Reduzca la frecuencia y mejore la relevancia en lugar de reenviar.

130429, 131048 y 131056: enviar demasiado rápido o demasiado

130429 es rendimiento: ponga los mensajes en cola y aplique retroceso. 131056 es a nivel de pareja: escribe demasiado a una misma persona. 131048 es una señal de calidad del número remitente y requiere corregir contenido y segmentación, no reintentar. Consulte límites de mensajería y calificación de calidad.

132000, 132001 y 132012: desajustes con la plantilla

Casi siempre son errores de integración. El nombre de la plantilla, el código de idioma (por ejemplo ar frente a en_US) y el número de variables deben coincidir exactamente con lo aprobado. Cree una prueba que envíe cada plantilla con valores de ejemplo cada vez que la edite.

Una política de reintentos que puede implementar

Use esta lista de verificación para clasificar cada fallo automáticamente.

1. Registre el código, el título, error_data.details, el ID del mensaje, el destinatario y el nombre de la plantilla.
2. No reintente nunca 131050, 131021, 132016, 368 y 131031. Avise de inmediato a un administrador de 368 y 131031.
3. Corrija y luego reintente los errores de autorización (0, 190, 10), de parámetros (131008, 131009, 135000), de plantilla (132000 a 132015) y de facturación (131042). Alerte al equipo responsable.
4. Aplique retroceso y reintente 130429, 4, 80007, 131016 y 131057 con retroceso exponencial y un tope.
5. Cambie de canal o de tipo de mensaje en 131047 (plantilla) y 131026 (SMS o correo electrónico).
6. Espere 24 horas o más en 131049 y revise la frecuencia de las campañas.
7. Informe de los fallos por código en los informes de campaña, no como un único total de «fallidos».

Ejemplo práctico: la promoción fallida de un minorista de Riad

Ejemplo sintético. «Najd Home» envía una plantilla de marketing a 20.000 clientes que han dado su consentimiento (opt-in). La API acepta todas las solicitudes, pero los webhooks de estado muestran unos 1.400 fallos.

Agrupados por código, el panorama es claro. El grupo más numeroso es 131049, así que el equipo excluye a esos usuarios de los dos envíos siguientes y reduce la frecuencia semanal. Un grupo menor es 131026; el análisis revela que muchos números estaban guardados con un cero inicial local, algo que se resuelve con una corrección de normalización. Varios usuarios con 131050 quedan suprimidos del marketing de forma permanente. Algunos errores 130429 provenían de la ráfaga inicial, por lo que ahora el envío se dosifica mediante una cola.

Errores comunes y límites reales

• Tratar todos los fallos como reintentables. Malgasta presupuesto y puede reducir la calidad.
• Fijar en el código los textos de Meta. Meta actualiza títulos y descripciones; base la lógica en el código numérico y mantenga una tabla de consulta que pueda actualizar.
• Ignorar error_data.details. A menudo señala el parámetro defectuoso exacto.
• No todos los fallos tienen solución. Algunos destinatarios no son alcanzables por WhatsApp, y Meta no explica todas las decisiones 131049. Prevea un canal alternativo.

Cómo ayuda OmniChannels.ai

OmniChannels.ai, con la tecnología de BroadNet Technologies, ofrece informes de entrega (DLR) en vistas resumida y avanzada, con filtros y exportación a CSV, para analizar los mensajes fallidos por campaña. El respaldo entre canales puede reenviar por RCS o SMS cuando falla WhatsApp, y las plantillas se previsualizan en una maqueta de teléfono y se siguen hasta su aprobación, lo que reduce los errores de desajuste. Los webhooks notifican los estados FAILED y REJECTED en un único formato normalizado, y la documentación para desarrolladores pública incluye una referencia de errores y límites.