Prueba Omnifox gratis 7 días gratis. Sin tarjeta de crédito.
Guías

Errores de la API de WhatsApp: 131031, 131047, 130429 y qué hacer con cada uno

Guía de los códigos de error más comunes de la API de WhatsApp (131031 cuenta bloqueada, 131047 ventana de 24 h, 130429 límite, 131049) y cómo resolverlos.

September 05, 2026
Errores de la API de WhatsApp: 131031, 131047, 130429 y qué hacer con cada uno
En este artículo

    Un mensaje que se queda en "enviado" y minutos después pasa a "fallido" es la forma en que la Cloud API te avisa de que algo se rompió. Y lo dice con un número. Los errores de la API de WhatsApp (131031, 131047, 130429 y sus vecinos) parecen crípticos, pero cada uno señala una causa concreta y una acción concreta. Aprender a leerlos ahorra horas de "probar de nuevo" y evita el error más común: reintentar un envío que va a fallar por la misma razón.

    Dos lugares donde aparece un error

    Antes de la tabla, un detalle que confunde a mucha gente: la API devuelve errores en dos momentos distintos.

    • En la respuesta del envío (síncrona): la petición se rechaza en el acto. Aquí aparecen errores como el 190 (token) o el 131009 (parámetro de plantilla). El mensaje nunca llega a existir.
    • En el webhook de estado (asíncrona): Meta acepta el mensaje, te devuelve un identificador, y después te avisa por webhook de que falló. Aquí llega el 131031 (cuenta bloqueada), el 131047 (fuera de ventana) o el 131026 (no entregable). Por eso el mensaje aparece primero como "enviado" y luego como "fallido".

    Si tu plataforma solo mira la respuesta del envío, verás campañas "exitosas" que en realidad no entregaron nada. Una bandeja que procesa los webhooks de estado (como hace Omnifox) muestra el cambio y el código en cada mensaje.

    Tabla de códigos: significado, causa y acción

    Código Qué significa Causa habitual Qué hacer
    131031 Business Account locked (cuenta bloqueada) Portafolio sin verificar, pago fallido o infracción de políticas Revisar el portafolio de Meta: verificación, avisos de política, método de pago. No reintentar hasta resolver
    131047 Re-engagement: fuera de la ventana de 24 horas Se envió texto libre a alguien que no escribió en las últimas 24 h Usar una plantilla aprobada para reabrir la conversación
    130429 Rate limit (límite de peticiones) Demasiadas llamadas a la API en poco tiempo Reducir el ritmo, encolar y reintentar con espera progresiva
    131049 Límite de mensajes de marketing por usuario ("healthy ecosystem") El destinatario ya recibió varias plantillas de marketing en poco tiempo No reintentar de inmediato; volver días después o cambiar a utilidad si aplica
    131026 Mensaje no entregable Número sin WhatsApp, inválido, o que te bloqueó Marcar el contacto; no insistir
    131048 Spam rate limit (por calidad) Muchos reportes o bloqueos de usuarios en poco tiempo Detener campañas, revisar contenido y listas, esperar la recuperación de calidad
    131056 Límite por par empresa-usuario Demasiados mensajes al mismo usuario en poco tiempo Espaciar los envíos a ese contacto
    190 Token expirado o inválido Token caducado, permisos revocados, cambio de contraseña del administrador Reconectar el canal desde la plataforma
    131009 Parámetro de plantilla inválido Variables que faltan, sobran o tienen formato distinto al aprobado Corregir los parámetros según la plantilla
    141006 Método de pago Tarjeta rechazada o ausente en el portafolio Actualizar el método de pago
    141010 Empresa sin verificar Acción que requiere verificación de empresa Completar la verificación en Meta

    Estos son los códigos que Meta documenta; si ves uno que no está aquí, consulta la referencia oficial de errores de la Cloud API en developers.facebook.com antes de suponer una causa.

    131031: el que te deja sin canal

    Es el más grave porque no afecta a un mensaje, afecta a toda la cuenta de WhatsApp Business. Lo dispara casi siempre una de tres cosas: un portafolio de Meta nuevo y sin verificar, un cobro que no pudo hacerse, o una infracción de políticas (muchos reportes, contenido prohibido, suplantación).

    La secuencia típica: el negocio lanza su primera campaña, los mensajes salen, y en el panel todos pasan a "fallido" con 131031. No es la campaña ni la plataforma; es el portafolio. La solución está en Meta: verificar la empresa, arreglar el pago o responder al aviso de política. Todo lo que debes dejar listo antes de conectar para que esto no pase está en el checklist antes de conectar la API de WhatsApp.

    131047: no es un error, es la ventana de 24 horas

    Este código aparece cuando intentas enviar un mensaje de texto libre a alguien que no te escribió en las últimas 24 horas. No hay nada roto. La regla de WhatsApp es que solo puedes responder libremente dentro de esa ventana; fuera de ella, necesitas una plantilla aprobada.

    Lo que un asesor suele intentar:

    Hola Carla, quedamos en que te confirmaba el precio del paquete a Cartagena. Son $890 por persona, todo incluido. ¿Te reservo?

    Si Carla escribió hace tres días, ese mensaje falla con 131047. La versión correcta es una plantilla de utilidad aprobada, por ejemplo:

    Hola {{1}}, tenemos lista la cotización que pediste para {{2}}.
    Responde este mensaje y te la enviamos con todos los detalles.
    

    Cuando Carla responde, la ventana se abre y el asesor puede escribir con libertad. Una bandeja bien configurada avisa al asesor de que la ventana está cerrada y le ofrece las plantillas antes de que falle el envío.

    130429 y 131056: velocidad, no contenido

    El 130429 es un límite de peticiones por segundo hacia la API; aparece cuando una campaña grande sale sin control de ritmo o una integración hace demasiadas llamadas seguidas. Se resuelve encolando y reintentando con esperas crecientes.

    El 131056 es parecido pero por destinatario: demasiados mensajes al mismo usuario en poco tiempo, casi siempre por una automatización en bucle o dos flujos escribiendo a la misma persona. La corrección es de lógica: un solo flujo por contacto, con tiempos de espera.

    131049 y 131048: Meta protege al usuario

    Estos dos son de la familia "salud del ecosistema" y son los que más frustran a marketing.

    • 131049: el destinatario ya recibió varios mensajes de marketing de distintas empresas en poco tiempo, y Meta decide no entregar otro. No es culpa de tu plantilla ni de tu calidad; es el límite por usuario. Reintentar en el acto no sirve; reintentar días después, sí. La estrategia para planificar campañas con esta regla la desarrollamos en límites de mensajes de marketing en WhatsApp 2026.
    • 131048: tu número está recibiendo demasiados reportes o bloqueos de usuarios y Meta frena los envíos. Aquí sí es culpa de la lista o del contenido. Detén las campañas, revisa quién dio opt-in y espera a que la calidad se recupere.

    Dónde mirar cuando no sabes qué pasa: health_status

    Cuando los errores se mezclan, la fuente de la verdad es el campo health_status del número en la API de Meta. Resume, para ese número, si puede enviar mensajes y, si no puede, por qué: cuenta bloqueada, límite de mensajería alcanzado, método de pago, nombre para mostrar pendiente, entre otros. Es lo que las plataformas muestran como "salud del canal".

    Antes de reintentar una campaña fallida, sigue este orden:

    1. Mira la salud del canal (estado del número, calidad, nivel de mensajería).
    2. Abre un mensaje fallido y lee el código exacto.
    3. Ubica el código en la tabla y actúa sobre la causa.
    4. Reintenta solo cuando la causa esté resuelta; si es 131049 o 131048, espera.
    5. Si el código es 131031, ve al portafolio de Meta, no a la plataforma.

    Preguntas frecuentes

    ¿Qué significa el error 131031 en WhatsApp?

    Significa que la cuenta de WhatsApp Business está bloqueada (Business Account locked), normalmente por un portafolio de Meta sin verificar, un pago fallido o una infracción de políticas. Llega en el webhook de estado, por eso el mensaje pasa de "enviado" a "fallido".

    ¿Cómo soluciono el error 131047?

    Enviando una plantilla aprobada en lugar de texto libre. El 131047 indica que el cliente no te escribió en las últimas 24 horas y la ventana está cerrada; cuando responda a la plantilla, podrás escribirle libremente.

    ¿El error 130429 significa que me bloquearon?

    No. Es un límite de peticiones por segundo hacia la API. Reduce el ritmo de envío y reintenta con esperas progresivas; el número no está restringido.

    ¿Por qué un mensaje aparece como enviado y luego como fallido?

    Porque Meta acepta la petición y después informa del resultado por webhook. Errores como 131031, 131047 o 131026 se conocen solo en ese segundo paso, así que el estado cambia cuando llega el aviso.

    Leer el código antes de reintentar

    Cada código es una instrucción. 131047 dice "usa plantilla"; 130429 dice "más despacio"; 131049 dice "hoy no, este usuario ya recibió suficiente"; 131031 dice "ve al portafolio". Reintentar sin leerlo solo empeora la calidad del número. Una bandeja que muestra el estado real de cada mensaje y la salud del canal convierte esos números en decisiones. Conoce la API oficial de WhatsApp en Omnifox o conecta tu número con la prueba gratis de 7 días.

    ¿Listo para probarlo en tu negocio?

    Reúne WhatsApp, Instagram, Messenger, email y llamadas en una sola bandeja, y deja que la IA dé la primera respuesta. Configúralo hoy mismo.

    7 días gratis. Sin tarjeta de crédito.

    Comentarios (0)

    Todavía no hay comentarios. Sé el primero en compartir tu opinión.

    Deja un comentario

    Tu email nunca se publica. Los comentarios se moderan antes de aparecer.

    Soporta markdown. El HTML se elimina.

    Leer más

    Escríbenos por WhatsApp