Esta guía enumera los códigos de error más comunes devueltos por la API de WhatsApp Business y proporciona acciones correctivas inmediatas para cada caso.

Cuando un envío falla, el sistema devuelve un registro (log) con detalles. Para diagnosticar el problema, concéntrate en el campo code (dentro del objeto errors).
A continuación, localiza el código correspondiente para entender qué ocurrió y cómo solucionarlo.

Lista de Errores y Soluciones

Error 131030: Destinatario inválido

Qué significa:
El número de teléfono al que intentaste enviar el mensaje no es una cuenta válida de WhatsApp o no existe.

Acción recomendada:

• Verifica que el número esté en el formato correcto (Código de país + código de área + número).
• Confirma con el cliente que tenga WhatsApp activo.

Importante:
Elimina este número de tu lista de envíos. Enviar repetidamente a números inexistentes perjudica la reputación de tu cuenta.

Error 131047: Ventana de 24 horas cerrada

Qué significa:
Han pasado más de 24 horas desde el último mensaje del cliente. Según las reglas de Meta, no se pueden enviar mensajes de sesión fuera de este período.

Acción recomendada:

• No intentes reenviar el mismo mensaje.
• Envía un Template aprobado para reabrir la conversación. Cuando el cliente responda, la ventana de 24 horas se renovará.

Error 131026: Mensaje no entregado (Violación)

Qué significa:
El mensaje no pudo entregarse, generalmente porque el usuario bloqueó a la empresa o el contenido viola alguna política.

Acción recomendada:

• Verifica si el contenido del template fue modificado recientemente.
• Si ocurre con un solo cliente, probablemente haya bloqueado tu número. Deja de enviarle mensajes.

Error 130429: Límite de tasa alcanzado

Qué significa:
La empresa alcanzó su límite diario de mensajes (Tier) o envió mensajes demasiado rápido en poco tiempo.

Acción recomendada:

• Revisa en qué Tier se encuentra tu cuenta (ej.: 1.000 o 10.000 mensajes/día).
• Reduce la velocidad de envío.
• Espera algunas horas antes de intentar nuevos envíos.

Error 131042: Fallo de pago

Qué significa:
Existe un problema de facturación en la cuenta de anuncios asociada a WhatsApp Business.

Acción recomendada:

• Accede a Business Manager > Facturación y regulariza el pago.
  El servicio de mensajería permanecerá pausado hasta que se resuelva.

Error 131049: Bloqueo por calidad (Spam)

Qué significa:
Meta bloqueó el envío para proteger la integridad del sistema debido a reportes o bloqueos recientes.

Acción recomendada:

• Detén los envíos inmediatamente.
• No insistas: continuar puede provocar el baneo permanente del número.
• Revisa tu estrategia y espera 24–48 horas enviando solo templates esenciales.

Error 131051: Tipo de medio no compatible

Qué significa:
El archivo enviado es demasiado grande, está dañado o no es compatible.

Acción recomendada:

• Verifica el tamaño (16MB para medios, 100MB para documentos).
• Convierte a formatos estándar (JPG, PNG, PDF, MP4).

Error 132000: Error de parámetros (variables)

Qué significa:
La cantidad de variables enviadas no coincide con las definidas en el template.

Acción recomendada:
Si el template espera 3 variables, tu JSON debe contener exactamente 3 parámetros.

Error 132001: Template inexistente

Qué significa:
No se encontró un template con el nombre indicado.

Acción recomendada:

• Verifica el nombre exacto (minúsculas y guiones bajos).
• Revisa el código de idioma.
• Confirma que el estado sea APPROVED.

Error 131031: Cuenta bloqueada

Qué significa:
La cuenta de WhatsApp Business (WABA) fue restringida por violaciones graves.

Acción recomendada:
Accede a Calidad de la Cuenta y solicita una revisión.

Error 131048: Bloqueo por tasa de spam

Qué significa:
Se alcanzó un límite específico de mensajes marcados como spam en poco tiempo.

Acción recomendada:
Detén el envío y revisa la última campaña; probablemente falte claridad u opción de opt-out.

Error 131056: Límite de mensajes por usuario

Qué significa:
Se enviaron demasiados mensajes a un mismo destinatario en poco tiempo.

Acción recomendada:
Espera unos minutos antes de enviar otro mensaje y evita mensajes consecutivos excesivos.

Error 368: Bloqueo temporal por política

Qué significa:
Bloqueo temporal aplicado por sistemas automáticos de integridad.

Acción recomendada:
Revisa el panel de Calidad de la Cuenta. Suele durar 24 horas.

Errores técnicos y de configuración

Error 133010: Número no registrado

Qué significa:
Tu número no está correctamente registrado en la API.

Acción recomendada:
Repite el registro (POST /register) o reconecta el número en tu BSP.

Error 131000: Error genérico

Qué significa:
Fallo temporal en los servidores de Meta.

Acción recomendada:
Espera y reintenta. Si persiste, abre un ticket con Meta.

Error 131053: Fallo al subir medios

Qué significa:
El archivo no pudo procesarse.

Acción recomendada:
Verifica tamaño, formato y estado del archivo.

Error 131008 / 131009: Parámetro obligatorio faltante

Qué significa:
La llamada a la API está incompleta o contiene valores inválidos.

Acción recomendada:
Revisa el JSON y asegúrate de que campos como type, to y template estén correctos.