Quienes operan con la API oficial conviven con una pantalla de errores escrita para desarrolladores: código numérico, frase en inglés y ninguna indicación de qué hacer. El resultado es previsible: el equipo trata todo como "error de WhatsApp", reenvía lo que no debería, cambia números que estaban saludables y culpa a la base por un problema de configuración. Este texto organiza ese caos en tres grupos, explica qué dice realmente cada fallo común y define, para cada uno, la única decisión correcta.
En este artículo
- Tres grupos, tres decisiones diferentes
- Errores de configuración
- Errores de base y destinatario
- Rechazos de la plataforma
- La ventana y el template: la confusión más costosa
- Límite, cuota y calidad
- Errores de medios y encabezado
- Qué puede y qué no puede reenviarse
- Cómo montar un panel de errores que decida
- Un envío en números
- Cinco errores al manejar errores
- Los números para monitorear
- Preguntas frecuentes
Tres grupos, tres decisiones diferentes
Lo primero que hay que hacer con una lista de fallos es dejar de tratarla como una sola lista. Todo rechazo de la API oficial cae en uno de tres grupos, y cada grupo exige una reacción diferente — opuestas, en algunos casos.
- Configuración. Algo del lado de la empresa está mal: template inexistente en ese número, permiso ausente, ventana cerrada, parámetro en formato inválido. Afecta todo el envío o una gran parte. Se corrige una vez y desaparece.
- Base y destinatario. El contacto es quien no permite la entrega: número sin cuenta en WhatsApp, teléfono mal digitado, dispositivo ausente por demasiado tiempo, bloqueo. Se distribuye por toda la lista en proporción estable.
- Rechazo de la plataforma. Meta decidió no entregar ese mensaje, por política, por límite o por criterio propio. No hay corrección del lado de la empresa y insistir empeora la situación.
La regla que separa la reacción es simple y vale para toda la operación: error de configuración se corrige y se reenvía; error de base se limpia en el registro; rechazo de la plataforma no se reenvía. Confundir el tercero con el primero es el comportamiento que más perjudica el número de una empresa seria.
Errores de configuración
Son los más frecuentes en operaciones nuevas y los más fáciles de resolver, porque tienen una firma clara: la tasa de fallo ronda el 100% desde el primer mensaje.
- Template no encontrado o no aprobado en ese número. La causa clásica en operaciones con rotación de números. El modelo fue aprobado en una cuenta comercial y el envío eligió un número de otra cuenta, donde no existe. No es un bug: la aprobación del template pertenece a la cuenta, no a la empresa.
- Número de parámetros diferente al esperado. El template tiene tres variables y el sistema envió dos, o el texto tiene salto de línea donde no puede. La frase devuelta suele mencionar "parámetro inválido" y rara vez indica cuál.
- Idioma incorrecto. El template existe en portugués de Brasil y el envío pidió portugués de Portugal. Son modelos diferentes para la plataforma.
- Permiso ausente. La cuenta o la aplicación no tiene la autorización necesaria para esa operación. Suele aparecer como error genérico de permiso y se resuelve en el panel de Meta, no en el código.
- Token expirado o cambiado. Deja de funcionar todo de golpe, incluyendo lo que funcionaba minutos antes.
El diagnóstico es siempre el mismo: si la falla comienza en el primer mensaje y afecta casi todos, detenga el envío. Dejarlo correr no descubre nada y gasta reputación.
Continúe leyendo gratis
Complete una vez y desbloquee este y todos los demás artículos del blog. No cobramos nada — solo queremos saber para quién estamos escribiendo.
Toma 20 segundos. ¿Prefiere hablar directo por WhatsApp?
Errores de base y destinatario
Estos aparecen dispersos en el envío, en proporción similar de una campaña a otra, y hablan sobre el registro de la empresa — no sobre el envío.
- Número sin cuenta en WhatsApp. El teléfono existe, pero no usa la aplicación. No hay qué reenviar. El valor está en marcar el contacto para no pagar por él cada mes.
- Número en formato inválido. Falta el código de país, sobra un carácter, el campo vino de una hoja de cálculo con máscara. Es rechazado antes de salir.
- Ortografía del celular brasileño. Caso particular y engañoso: números antiguos guardados sin el noveno dígito, o con un dígito que esa región no usa. Quien decide qué ortografía existe es el propio WhatsApp, y la única forma correcta es consultar antes de enviar en vez de adivinar por los dígitos.
- Expiración. El mensaje esperó a que el dispositivo apareciera y el plazo terminó. No es número inválido — es dispositivo ausente. Reenviar en otro horario suele recuperar buena parte.
- Bloqueo por parte del destinatario. Esa persona bloqueó a la empresa. Es definitivo y hay que marcar el registro, bajo pena de que la lista siga pagando y degrade la calidad.
Rechazos de la plataforma
Aquí está el grupo que más genera decisiones erróneas, porque el mensaje devuelto parece un defecto y no lo es.
- Mensaje no pudo ser entregado. Rechazo genérico, sin motivo detallado. Puede ser filtro antifraude, comportamiento del destinatario o criterio interno. No se reenvía.
- Número en experimento de la plataforma. Meta separa grupos de usuarios para pruebas internas y rechaza envíos para ellos. No tiene relación con la empresa ni con la base, y no cambia por insistencia.
- Template pausado por calidad. Ese modelo específico acumuló bloqueos y fue suspendido. El número sigue saludable y los otros templates funcionan — cambiar de número no resuelve, reescribir el mensaje sí.
- Restricción por política. Contenido que la plataforma no acepta, incluso con template aprobado.
La confusión típica: el equipo ve muchos de estos rechazos, concluye que "el número está quemado" y migra el envío a otro número. El envío se reinicia, aparecen los mismos rechazos, y ahora son dos números con peor calidad. El camino correcto es revisar qué está rechazando la plataforma, aceptar la parte que no depende de la empresa y revisar el contenido cuando la proporción sube.
La ventana y el template: la confusión más costosa
Gran parte de las fallas en operaciones nuevas proviene de un malentendido único sobre cuándo puede usarse cada tipo de mensaje.
Cuando el cliente escribe a la empresa, se abre una ventana de atención — comúnmente de 24 horas — en la que la empresa responde con mensaje libre, como quiera. Fuera de esa ventana, el mensaje libre es rechazado, y el único camino es un template aprobado.
Los dos errores reflejados:
- Intentar mensaje libre fuera de la ventana. Ocurre cuando la automatización responde a un contacto antiguo, o cuando el agente abre una conversación archivada y escribe. El rechazo menciona la ventana, y la corrección es usar template.
- Usar template con la ventana abierta. No falla, pero cuesta dinero innecesariamente y suena robótico para quien acaba de escribir.
Existe una variación que confunde aún más: en Instagram Direct y Messenger la lógica de ventana también existe, con reglas propias. Un bloqueo escrito pensando solo en WhatsApp acaba bloqueando respuestas legítimas en otros canales — el cliente escribió, la ventana está abierta, y el sistema rechaza porque aplicó la regla errónea. Quien manda es el canal de esa conversación.
Límite, cuota y calidad
Tres cosas diferentes que el equipo suele llamar con el mismo nombre.
El límite de conversaciones iniciadas es el techo de cuántos contactos nuevos ese número puede abrir en un período. Sube conforme la operación demuestra volumen y calidad. Cuando se alcanza, la falla aparece en medio del envío — empieza bien y degrada.
La calidad del número es un indicador de la plataforma, basado en bloqueos y denuncias. Calidad baja no impide el envío por sí sola, pero suele venir acompañada de restricción de límite y es la alarma que antecede un problema serio.
La pendencia financiera es la más silenciosa: cuenta comercial con factura pendiente puede tener envíos bloqueados incluso con número verde y template aprobado. La falla no dice "factura pendiente" — dice algo genérico —, y el equipo pasa horas buscando defecto técnico. Vale la revisión antes de cualquier investigación larga.
Errores de medios y encabezado
Template con imagen, video o documento en el encabezado tiene una categoría propia de fallas, y suelen diagnosticarse mal porque la frase devuelta habla de parámetro.
- Formato no aceptado. Imagen en formato exótico, PNG con transparencia o perfil de color inusual, archivo con extensión que no corresponde al contenido.
- Tamaño por encima del límite. Cada tipo de medio tiene un techo propio.
- Identificador de medio de otro número. Archivo enviado a la plataforma queda asociado al número que lo envió. Usar ese identificador en otro número falla — de nuevo, la rotación choca con esto.
- Dirección de medio expirada. Enlaces de archivos alojados por la propia plataforma tienen validez corta y no sirven para reenvío posterior.
Un principio de diseño vale oro aquí: la preparación del medio no debería derribar el envío. Si la conversión de una imagen falla pero el archivo original ya está en formato aceptado y dentro del límite, lo correcto es seguir con el original y dejar que la plataforma decida — no interrumpir todo el envío por una etapa auxiliar.
Qué puede y qué no puede reenviarse
La tabla mental que evita la mayor parte de los daños:
- Reenviar después de corregir: template incorrecto, parámetro inválido, idioma cambiado, permiso ausente, token expirado, falla de red del propio servidor.
- Reenviar después de un intervalo, en otro horario: expiración por dispositivo ausente.
- Nunca reenviar: rechazo genérico de la plataforma, número en experimento, bloqueo por destinatario, número sin cuenta en WhatsApp, restricción por política.
Y una regla de oro para automatización: reenvío automático en bucle está prohibido. Un sistema que intenta de nuevo solo, sin clasificar el motivo, convierte un rechazo aislado en cientos de intentos contra el mismo destinatario — que es exactamente el patrón que la plataforma penaliza.
Cómo montar un panel de errores que decida
Un panel útil tiene cuatro características, y ninguna es técnica.
Primero: mensaje en español. Código numérico y frase en inglés no dicen nada a quien opera. "Failed to send message because this user's phone number is part of an experiment" debe aparecer como "Meta bloqueó este número por estar en una prueba interna". El texto original puede guardarse para investigación, pero no es lo que muestra la pantalla.
Segundo: agrupamiento por motivo, con conteo. Treinta líneas iguales no son treinta problemas; son un problema con treinta ocurrencias.
Tercero: clasificación por grupo — configuración, base o plataforma — para que la decisión salga del propio panel.
Cuarto: acción sugerida por grupo. Reenviar, limpiar registro, corregir configuración o aceptar. Sin esto, todo error se vuelve un ticket.
Un envío en números
Un envío de ejemplo, con 3.173 contactos, muestra cómo la clasificación cambia la lectura.
El panel sin agrupamiento muestra 130 líneas rojas y la conclusión del equipo es "el envío falló". Agrupado, el cuadro es otro:
- 62 números sin cuenta en WhatsApp — 2,0% de la base
- 34 rechazos genéricos de la plataforma — 1,1%
- 19 expiraciones por dispositivo ausente — 0,6%
- 11 números en experimento de la plataforma — 0,3%
- 4 bloqueos — 0,1%
Son 130 fallas en 3.173, o 4,1% — nivel normal. Y las decisiones son tres, no una: 62 contactos salen de la base y dejan de costar; 19 entran en un reenvío programado para otro horario; y los 49 restantes son rechazos de la plataforma que no tienen acción alguna. Ninguna línea de este informe justifica cambiar de número, reescribir el template o abrir un ticket — que es exactamente lo que habría pasado ante las 130 líneas rojas sueltas.
Cinco errores al manejar errores
- Reenviar lo que la plataforma rechazó. El resultado es el mismo y la calidad del número cae con cada intento.
- Cambiar de número ante rechazo de la plataforma. Lleva el problema al número nuevo y ahora son dos con historial malo.
- Dejar el envío correr con alta falla desde el inicio. Fallo de configuración no se descubre insistiendo; se descubre deteniendo.
- Mostrar el texto de Meta en la pantalla del operador. Error en inglés no produce decisión — produce ticket.
- Buscar defecto técnico antes de revisar la cuenta. Factura pendiente y permiso ausente causan fallas que parecen bug y se resuelven en el panel de Meta.
Los números para monitorear
Cinco indicadores mantienen la operación bajo control. La tasa total de fallos por envío, comparada con el promedio histórico de la empresa, que es la alarma más simple. La composición de fallas por grupo — configuración, base y plataforma —, que indica quién debe actuar. El porcentaje de contactos inválidos en la base, que solo baja con trabajo de registro y que cuesta dinero en toda campaña. La tasa de bloqueo, el indicador más sensible de todos, que antecede la caída de calidad del número. Y la cantidad de reenvíos automáticos disparados, que debería ser cercana a cero para rechazos de la plataforma — cuando ese número crece, el sistema está trabajando contra la propia operación.
Preguntas frecuentes
¿Puedo reenviar un mensaje que la API rechazó?
Depende del grupo en que encaje el rechazo, y confundirlos es lo que más perjudica el número de una empresa seria. Errores de configuración — template inexistente en ese número, parámetro inválido, idioma cambiado, permiso ausente, token expirado — deben corregirse y reenviarse. Expiración por dispositivo ausente puede reenviarse después de un intervalo, preferentemente en otro horario. Ya rechazo de la plataforma nunca debe reenviarse: mensaje que no pudo ser entregado, número en experimento interno de Meta, bloqueo por destinatario, número sin cuenta en WhatsApp y restricción por política no cambian de resultado por insistencia, y cada nuevo intento gasta reputación. Vale también una regla de automatización: reenvío automático en bucle, sin clasificar el motivo, convierte un rechazo aislado en cientos de intentos contra el mismo destinatario — exactamente el patrón que la plataforma penaliza.
¿Qué significa "this user's phone number is part of an experiment"?
Significa que Meta separó ese número para una prueba interna y está rechazando envíos para él. No tiene relación con su empresa, con su base ni con la calidad de su número, y no cambia por insistencia: reenviar produce exactamente el mismo rechazo. Es una de las fallas del grupo "rechazo de la plataforma", en que no existe corrección del lado de quien envía. En un envío saludable estas ocurrencias aparecen en proporción pequeña y estable, y la decisión correcta es registrarlas y seguir. El problema práctico es otro: como el mensaje llega en inglés y sin explicación, el equipo interpreta como defecto, concluye que el número está quemado y migra el envío a otro número — lo que no resuelve nada y aún pone un segundo número en la misma situación.
Mi envío comenzó fallando en casi todo. ¿Qué hacer?
Detener inmediatamente. Falla alta desde el primer mensaje casi nunca es problema de la base — es configuración, y dejar correr no descubre nada mientras gasta reputación. Las causas más comunes son template inexistente o no aprobado en ese número específico, que es la clásica en operaciones con rotación; número de parámetros diferente al que el template espera; idioma cambiado, ya que portugués de Brasil y de Portugal son modelos diferentes; permiso ausente en la cuenta o en la aplicación; y token expirado, que derriba todo de golpe, incluso lo que funcionaba minutos antes. El diagnóstico es rápido cuando las fallas están agrupadas por motivo: una causa dominante con cientos de ocurrencias apunta directo a qué corregir. Después de corregido, el reenvío es legítimo, porque el error era de la empresa y no un rechazo de la plataforma.
La imagen del template está fallando. ¿Es error de Meta?
Normalmente no. Template con medio en el encabezado tiene una familia propia de fallas, y se diagnostican mal porque el mensaje devuelto suele hablar de "parámetro inválido" en vez de mencionar la imagen. Las causas más comunes son formato no aceptado, tamaño por encima del límite de ese tipo de medio, identificador de archivo perteneciente a otro número — el archivo enviado a la plataforma queda asociado al número que lo envió, y reutilizarlo en otro falla — y dirección de medio expirada, ya que los enlaces alojados por la plataforma tienen validez corta. Vale un principio de diseño: la preparación del medio no debería derribar el envío. Si la conversión de una imagen falla pero el archivo original ya está en formato aceptado y dentro del límite, lo correcto es seguir con el original y dejar que la plataforma decida, en vez de interrumpir todo el envío por una etapa auxiliar.
¿Por qué falla el mensaje incluso con número verde y template aprobado?
Hay tres causas frecuentes que no aparecen en el estado del número. La primera es el límite de conversaciones iniciadas: existe un techo de cuántos contactos nuevos ese número puede abrir en un período, y cuando se alcanza la falla aparece en medio del envío — que empieza bien y degrada. La segunda es la pausa de ese template específico por calidad: el modelo acumuló bloqueos y fue suspendido mientras el número sigue saludable y los demás templates funcionan, lo que significa que cambiar de número no resuelve y reescribir el mensaje sí. La tercera es la más silenciosa: pendiente financiera en la cuenta comercial puede bloquear envíos incluso con todo verde, y la falla devuelta no dice "factura pendiente" — dice algo genérico. Vale revisar la cuenta antes de comenzar cualquier investigación técnica larga.
Error que no se convierte en decisión se convierte en ticket
VeyloCRM traduce cada rechazo de Meta al español, agrupa las fallas por motivo en vez de listar líneas sueltas, separa lo que es configuración, base y rechazo de la plataforma, no reenvía lo que Meta bloqueó y mantiene WhatsApp, Instagram y Messenger en el mismo panel — para que el equipo sepa qué hacer sin abrir un ticket en cada campaña.