Errores de WhatsApp Business API: qué significa cada código y cómo resolverlo

Meta devuelve el código en la respuesta de la API o en el webhook de estado del mensaje, dentro del objeto errors. Esta es la lectura práctica de los que más aparecen en operaciones de LATAM:

Es, por lejos, el error más común. La API solo permite enviar mensajes de texto libre mientras la ventana de servicio de 24 horas esté abierta, es decir, dentro de las 24 horas posteriores al último mensaje del usuario. Pasado ese plazo, cualquier intento de texto libre devuelve 131047.

La solución no es reintentar: es enviar una plantilla HSM aprobada, que sí puede reabrir la conversación. El código 470 es el equivalente heredado de la API On-Premise, que Meta dejó de mantener a favor de la Cloud API.

Si ves picos de 131047, revisa tu lógica de cola: normalmente son respuestas de agentes escritas horas después, o automatizaciones que se disparan con retraso.

131026 significa que el mensaje no se pudo entregar. Las causas habituales son que el número no tiene cuenta de WhatsApp, que está mal formateado (falta el código de país o sobra un prefijo local), o que el dispositivo no puede recibir ese tipo de contenido. Antes de culpar a la integración, valida el formato E.164 de tu base.

131049 es distinto: Meta decidió no entregar ese mensaje de marketing en particular para cuidar la experiencia de la persona. Aparece cuando un usuario ya recibió varios mensajes promocionales y no interactúa. No se arregla con código: se arregla enviando menos y mejor. Y no conviene reintentar en bucle: los reintentos excesivos pueden bloquear el envío a esa persona hasta 24 horas.

132000 aparece cuando la cantidad de parámetros que envías no coincide con la cantidad de variables que declara la plantilla aprobada. Es típico después de editar una plantilla sin actualizar el código que la consume, o al reutilizar el mismo payload para dos idiomas distintos.

133010 indica que el número todavía no está registrado en la API. Sucede cuando se agregó el número a la cuenta pero no se completó el registro con el PIN de verificación en dos pasos, o después de una migración entre proveedores en la que faltó ese paso.

Ambos se detectan rápido en ambiente de pruebas: envía siempre una plantilla de cada tipo antes de liberar un cambio a producción.

El código 368 indica que la cuenta quedó temporalmente restringida por incumplir las políticas de WhatsApp Business. No se resuelve reintentando ni cambiando de número: hay que corregir la causa, que casi siempre es una combinación de contactos sin consentimiento, contenido fuera de política y frecuencia excesiva.

El camino correcto es revisar el estado en el Administrador de WhatsApp, corregir el contenido y el proceso de opt-in, y recién después retomar envíos de forma gradual. La guía de cómo evitar bloqueos detalla las causas más frecuentes.

1. Mira el webhook, no la respuesta HTTP. Un 200 al enviar no garantiza entrega: el fallo llega después en el estado del mensaje.
2. Separa errores por código. Si el 80% es un solo código, es un problema sistémico, no de casos sueltos.
3. Verifica si el error es de ventana, de datos o de política. Ventana → plantillas. Datos → formato y parámetros. Política → calidad y consentimiento.
4. Revisa el estado de tus plantillas. Una plantilla pausada genera fallos aunque tu código esté perfecto.
5. Controla tu límite de mensajes y tu calidad. Consulta los límites de mensajes antes de escalar un envío.