Los códigos de error de la API de WhatsApp que de verdad te vas a encontrar

La lista oficial de errores de la API de WhatsApp Business es larga. En la práctica, si integras mensajería con un CRM, te vas a topar una y otra vez con un puñado muy concreto. Esta guía cubre esos, con el contexto que la documentación da por supuesto.

131047: Re-engagement message

Qué significa: intentaste enviar texto libre fuera de la ventana de 24 horas.

Por qué desconcierta: porque el envío devolvió 200. Meta acepta el mensaje, te da un identificador, y lo descarta después. El error solo aparece en la actualización de estado que llega por webhook.

Solución: fuera de la ventana solo se puede enviar una plantilla aprobada. No hay atajo. Si tu automatización escribe a contactos que no te han escrito antes, tiene que usar plantilla siempre.

131008: Required parameter is missing

Qué significa: la plantilla que intentas enviar declara un parámetro que no estás rellenando.

El caso que más se repite: un botón de tipo URL con una variable dentro de la dirección (https://…/{{1}}). Al registrarlo así, la plantilla exige un componente button en cada envío. Muchas herramientas de automatización no ofrecen un campo para ese valor, con lo que la plantilla queda aprobada pero es inenviable.

Solución: registra el botón con URL estática y mueve la variable al cuerpo del mensaje. Si ya tienes la plantilla creada, tendrás que duplicarla corregida: no se puede editar el tipo de botón de una plantilla aprobada.

190: Cannot parse access token

Qué significa: el token que estás mandando no es un token válido.

Por qué aparece cuando "el token es correcto": casi siempre porque lo que se envía no es el token, sino su versión cifrada, o una cadena truncada al guardarla. Es un error de almacenamiento, no de permisos.

Solución: comprueba qué llega literalmente a la cabecera Authorization. Si guardas tokens cifrados en base de datos, y deberías, asegúrate de descifrarlos justo antes de usarlos.

132000 y familia: la plantilla y los parámetros no cuadran

Qué significa: el número de variables que envías no coincide con el que la plantilla espera.

Solución: trata la plantilla como un contrato. Si tiene tres variables, los tres valores son obligatorios y en orden. Una plantilla editada en Meta y no actualizada en tu sistema rompe aquí.

368 / restricciones de calidad

Qué significa: tu número ha sido limitado por calidad, normalmente porque una proporción alta de destinatarios bloqueó o reportó tus mensajes.

Solución: esto no se arregla con código. Se arregla enviando menos y mejor: a gente que espera tu mensaje, con plantillas que aportan algo. La calificación de calidad se recupera con el tiempo si el comportamiento cambia.

El error que no tiene código

El más caro no aparece en ninguna lista: contar el 200 como entrega.

La API responde 200 cuando acepta el mensaje para procesarlo. Lo que ocurre después llega por webhook, en una secuencia de estados:

sent  →  delivered  →  read
failed + código de error

Si tu sistema no escucha ese webhook, o lo escucha pero no persiste el estado, tu informe dirá que todo salió bien. Es un fallo silencioso: nadie ve una excepción, nadie recibe una alerta, y el número que miras es sencillamente falso.

Una fila que dice sent para siempre porque nadie escribió el resultado del webhook es peor que una fila que dice failed. La segunda la investigas.

Cómo diagnosticar bien un envío

1. La respuesta síncrona solo confirma aceptación. Guarda el identificador de mensaje y sigue adelante.
2. El veredicto está en el webhook de estados. Persistelo asociado a ese identificador.
3. Registra el código de error, no solo el fallo. 131047 y 131008 tienen causas y soluciones opuestas; "falló" no te dice nada.
4. Comprueba antes de enviar lo que se puede comprobar. El estado de la ventana y la forma de la plantilla se conocen de antemano. Enviar algo que sabes que va a fallar solo ensucia tu calidad de número.

Resumen

Y el que no lleva número: medir aceptaciones creyendo que son entregas.