Errores de WhatsApp API: qué significa cada código y qué hacer

Cuando un mensaje de WhatsApp API falla, Meta devuelve un número, y ese número dice casi todo. El 131042 es un problema con el método de pago, el 131047 significa que pasaron más de 24 horas desde que el cliente te escribió y el 131026 indica que el destinatario no puede recibir el mensaje. Esta guía reúne los códigos que más frenan a una empresa que envía campañas y notificaciones, qué los causa y qué hacer con cada uno, según la documentación de errores de Meta actualizada en junio de 2026.

¿Cómo leo un error de WhatsApp API?

Cada error trae un número, una explicación en texto y un identificador de rastreo. Meta pide que tu sistema decida qué hacer mirando el número, no el título del error ni el estado HTTP. En su lista de códigos de error lo dice así: «Basa la administración de errores de tu app en códigos de error, no en subcódigos ni códigos de estado de respuesta HTTP.»

En la práctica importan tres campos:

• code: el número que identifica el problema. Guárdalo en tus registros de envío.
• details: la causa más probable, y a veces el parámetro que sobra o falta.
• fbtrace_id: el identificador que Meta te pide cuando abres un caso de soporte.

Los errores llegan por dos caminos: en la respuesta inmediata de la API y en el webhook de mensajes. Un envío que la API recibió sin problema puede aparecer después como fallido en el webhook, así que tu equipo tiene que mirar los dos.

¿Qué hago si el error es de pago o de cuenta?

El 131042 aparece cuando algo falla con el método de pago de la cuenta de WhatsApp Business. Meta enumera las causas más comunes:

• La cuenta de pago no está anexada a la cuenta de WhatsApp Business.
• La línea de crédito llegó a su límite, o nunca se configuró ni se activó.
• Falta configurar la zona horaria o la divisa.
• La cuenta de WhatsApp Business fue eliminada o suspendida.

Con el cobro que rige desde el 1 de octubre de 2026, revisar la facturación ya no es opcional para nadie: la documentación de precios de Meta advierte que a las cuentas sin forma de pago al cierre de septiembre les dejó de entregar las respuestas de servicio.

Los códigos 368 y 131031 indican que la cuenta quedó restringida o desactivada por incumplir una política de la plataforma. El 131031 también sale cuando un dato del envío no coincide con la cuenta, por ejemplo un PIN de verificación en dos pasos equivocado. Reintentar no sirve: primero hay que saber por qué Meta restringió la cuenta. Si es un bloqueo, en esta guía explicamos cómo apelarlo.

¿Por qué falla si el cliente me escribió ayer?

Falla porque la ventana de atención dura 24 horas. El 131047 significa que pasaron más de 24 horas desde la última respuesta del cliente, y fuera de esa ventana solo puedes escribirle con una plantilla aprobada. La salida es enviar la plantilla que corresponda al contenido del mensaje y retomar la conversación libre cuando la persona responda.

Los errores de plantilla son otra familia frecuente:

• 132000: la cantidad de variables que envías no coincide con las que define la plantilla.
• 132001: la plantilla no existe en ese idioma o no está aprobada. Revisa el nombre y el código de idioma.
• 132012: las variables llegan con un formato distinto al que fijaste en la plantilla.
• 132015: la plantilla quedó en pausa por baja calidad. Edítala y espera la nueva aprobación.
• 132016: se pausó tantas veces que Meta la desactivó para siempre. Toca crear otra con un texto diferente.

¿Qué significa que llegué al límite de envíos?

Significa cosas distintas según el código, porque hay tres límites y cada uno tiene el suyo:

• 130429: tu integración superó la cantidad de mensajes que la API admite. Baja el ritmo de envío y reintenta más tarde.
• 131056: le mandaste demasiados mensajes al mismo número en poco tiempo. Puedes seguir escribiendo a otros contactos; a ese, toca esperarlo.
• 131048: el número tiene restricciones porque muchos mensajes anteriores fueron bloqueados o marcados como spam. Aquí el problema es la calidad, no la velocidad.

Un cuarto código se confunde con estos: el 131049. Meta no entregó el mensaje para cuidar la experiencia de los usuarios y lo relaciona con su límite de mensajes de marketing por persona. Reintentar enseguida solo devuelve el mismo error, y Meta recomienda esperar al menos 24 horas antes de volver a enviar esa plantilla.

¿Por qué un mensaje sale como enviado y nunca llega?

Muchas veces Meta no explica la causa. Su página de soporte reconoce que, por razones de privacidad y de políticas, no revela por qué un mensaje enviado no se entregó. Los motivos más comunes que enumera son estos:

• El cliente no se conectó a WhatsApp durante los 30 días en que Meta guarda los mensajes pendientes.
• El cliente bloqueó tu número.
• El cliente está en un país con restricciones o sanciones.

Cuando sí hay código, el más común es el 131026: ese número no usa WhatsApp, la persona no ha aceptado las condiciones del servicio más recientes o tiene una versión vieja de la app. Meta sugiere buscarla por otro canal y pedirle que actualice. El 131050 es distinto y no admite insistencia: la persona eligió no recibir más mensajes de marketing de tu empresa.

Ahí está la razón práctica para tener un canal de respaldo. Si una notificación importante (un pago, una cita, un código de acceso) no llega por WhatsApp, un SMS o un correo pueden cubrir ese hueco. Los datos de por qué el SMS sigue llegando donde otros canales no llegan están en esta guía sobre el SMS.

¿Cuándo vale la pena reintentar y cuándo no?

Vale la pena reintentar solo cuando el error es temporal. Esta es la forma de ordenarlos:

• Reintenta en unos minutos: los códigos 1, 2, 131016 y 133004 son caídas o sobrecargas del servicio. Antes, mira la página de estado de la plataforma. Con el 131000, un error desconocido, Meta pide intentar de nuevo y abrir un caso si se repite.
• Corrige y después reintenta: 100, 131008, 131009 y 132000 son parámetros que faltan, están mal escritos o traen valores no válidos.
• Espera antes de reenviar: 131049 y 131056, porque insistir enseguida repite el error.
• No reintentes: 131050 (la persona no quiere marketing), 130403 (tu empresa bloqueó a ese usuario) y 132016 (plantilla desactivada).

Si el problema sigue, abre un caso de soporte con el fbtrace_id a la mano. Meta intenta dar una primera respuesta en 24 horas en días laborables, pero si un proveedor de soluciones conectó tu número, el caso se tramita con ese proveedor y no directamente con Meta.

Empieza por sacar de tus envíos de la última semana los cinco códigos que más se repiten: con esa lista sabes si te toca corregir plantillas, pagos o ritmo. Si quieres que una notificación que falla por WhatsApp salga por SMS o correo desde el mismo panel, mira cómo lo organiza Campañas Omnicanal de Getincloud.