¿Tu integración con WhatsApp Business está fallando? Los errores de API pueden interrumpir tus ventas y afectar la experiencia de tus clientes. Estos problemas suelen estar relacionados con límites de solicitudes, tokens vencidos, permisos mal configurados o errores en plantillas de mensajes. Si no se resuelven, pueden bloquear mensajes esenciales, reducir el nivel de tu cuenta (Tier) e incluso dañar la confianza de tus compradores.
¿El objetivo? Minimizar errores, mantener una integración fluida y proteger tus ventas. Sigue leyendo para aprender cómo identificar y resolver estos problemas antes de que afecten tu operación.
Códigos de error comunes de WhatsApp Business API y sus soluciones
Cuando trabajás con la API de WhatsApp Business, entender los errores de autenticación es clave para resolver problemas. Estos errores ocurren cuando tu sistema no puede verificar su identidad con la Graph API de Meta o carece de los permisos necesarios para realizar una acción. Se manifiestan a través de respuestas HTTP o webhooks. Para identificarlos, es fundamental analizar los valores de "code" y "details" en las respuestas JSON.
"Meta recomienda que construyas la lógica de manejo de errores de tu aplicación en torno a los valores de
codey las propiedades del payloaddetails. Estas propiedades y sus valores son más indicativos del error subyacente." - Meta Developer Documentation
Una herramienta imprescindible en este proceso es el Access Token Debugger, que te permite verificar los permisos de tu token y confirmar si sigue siendo válido. Si te encontrás con códigos como 0, 190 o 10, esta herramienta te ayudará a identificar qué falla y qué permisos están ausentes.
| Código | Estado HTTP | Significado | Causa común | Solución |
|---|---|---|---|---|
| 0 | 401 | AuthException | Token expirado, revocado o usuario bloqueó el acceso de la app | Generá e implementá un nuevo token |
| 190 | 401 | Token de acceso expirado | El token alcanzó su fecha de vencimiento | Refrescá el token u obtené uno nuevo desde el portal de Meta |
| 10 | 403 | Permiso denegado | Faltan scopes requeridos, cuenta no elegible o número no autorizado | Verificá scopes y elegibilidad de la cuenta con Access Token Debugger |
| 200-299 | 403 | Permiso de API | El permiso para el endpoint específico no está otorgado o fue removido | Verificá y habilitá los permisos requeridos en el App Dashboard |
Para evitar estos problemas, es útil automatizar el proceso de refresco de tokens y monitorear las respuestas de error, como "entry.changes.value.errors", para detectar fallos de autenticación de forma temprana. Además, conservá siempre el fbtrace_id de cada respuesta de error, ya que es crucial para que el soporte de Meta pueda rastrear y resolver problemas específicos.
Con estas estrategias, podés reducir al mínimo los errores de autenticación y mantener una integración fluida con la API.
Tras analizar los errores de autenticación, es momento de hablar sobre los problemas relacionados con la entrega de mensajes y los límites de tasa. Estos inconvenientes pueden interrumpir la comunicación con los clientes, afectando directamente su experiencia de compra.
En la API de WhatsApp Business, los errores de entrega se reportan de dos formas. Algunos se notifican de manera sincrónica como respuesta inmediata de la Graph API (por ejemplo, cuando se envían parámetros incorrectos o se usan tokens vencidos). Otros se reciben de forma asincrónica a través de webhooks, cuando un mensaje falla después de haber sido aceptado inicialmente por la API.
Es clave monitorear entry.changes.value.messages.errors en los webhooks en entornos de producción, ya que muchas fallas ocurren después de la llamada inicial a la API. Las razones más comunes incluyen que el número del destinatario no esté registrado en WhatsApp, que el usuario no haya aceptado los Términos de Servicio más recientes o que esté usando una versión antigua de la aplicación. Otro error frecuente es intentar enviar un mensaje regular fuera de la ventana de conversación de 24 horas, cuando en realidad se necesita un mensaje de plantilla preaprobado. A continuación, se presentan los códigos de error más comunes junto con las acciones recomendadas.
| Código de error | Título | Causa | Acción recomendada |
|---|---|---|---|
| 4 | API Too Many Calls | Se alcanzó el límite de tasa a nivel de aplicación | Reducí la frecuencia de las llamadas a la API. |
| 80007 | Rate Limit Issues | Se alcanzó el límite de tasa a nivel de WABA | Disminuí el envío de mensajes y verificá los límites de tu WABA. |
| 131021 | Recipient Cannot Be Sender | Los números de remitente y destinatario son idénticos | Usá un número de destinatario diferente. |
| 131026 | Message Undeliverable | El destinatario no está en WhatsApp, usa una versión antigua o no aceptó los términos | Pedí al usuario que actualice su app o acepte los términos por otros medios. |
| 130429 | Rate Limit Hit | Se alcanzó el límite de la Cloud API | Implementá una espera exponencial y reintentá más tarde. |
| 131047 | Re-engagement Message | Fuera de la ventana de 24 horas | Enviá un mensaje de plantilla preaprobado. |
| 131056 | Pair Rate Limit Hit | Demasiados mensajes a un destinatario específico | Esperá antes de enviar más mensajes a ese número. |
Para reducir estos errores, asegurate de que el número esté en formato E.164 y de que el destinatario sea un usuario activo de WhatsApp. Si encontrás errores como el 131057 o el 2494100, probablemente el número o la cuenta estén en mantenimiento por actualizaciones; en este caso, intentá nuevamente después de unos minutos.
Meta sugiere diseñar la lógica de manejo de errores basándote en los valores del campo code y en las propiedades del payload details, ya que los títulos de los mensajes de error pueden cambiar con el tiempo. Además, conservá siempre el fbtrace_id de cada respuesta de error, ya que será útil para rastrear el problema con el soporte técnico si es necesario.
Los webhooks son esenciales para enviar notificaciones asíncronas clave a tu plataforma. Cuando fallan, el flujo de datos se interrumpe, afectando confirmaciones de entrega, respuestas de clientes y alertas de errores generadas tras la aceptación inicial de un mensaje por la API. A diferencia de los errores sincrónicos, que aparecen de inmediato en la respuesta de la Graph API, los problemas con webhooks interrumpen la comunicación de manera silenciosa, lo que puede dejarte sin información sobre el estado de tus mensajes. Configurar correctamente los webhooks es crucial para garantizar la continuidad de la comunicación y evitar problemas en tu tienda online. A continuación, revisamos algunos códigos de error comunes y sus soluciones.
El código de error 131016 (Service Unavailable) refleja un fallo temporal del servicio con un estado HTTP 500. Por otro lado, el error con código 2, acompañado de un HTTP 503, ocurre cuando la API está sobrecargada o fuera de servicio. En estos casos, Meta sugiere consultar la página de estado de la plataforma de WhatsApp Business para verificar si el problema es generalizado. Si se trata de un error temporal en los webhooks, intentá reenviar la solicitud aplicando una estrategia de espera exponencial.
Otro error frecuente es el 2388103, que indica que los webhooks no están configurados en la cuenta de WhatsApp Business de destino durante una migración de número telefónico. Este error impide recibir notificaciones hasta que se suscriba correctamente la aplicación a los webhooks en la cuenta correspondiente.
Para solucionar estos problemas, verificá que tu aplicación esté suscrita a los campos "messages" y "errors" del webhook. Los errores suelen encontrarse en las rutas JSON "entry.changes.value.errors" o "entry.changes.value.messages.errors" del payload recibido.
En caso de migración, asegurate de que el número comercial tenga un "name_status" aprobado y que ambas cuentas pertenezcan al mismo negocio con una línea de crédito activa. Si enfrentás el error 2388103, suscribí tu aplicación a los webhooks de la cuenta de destino antes de continuar con la migración.
Para mantener una visibilidad completa de los errores, es importante monitorear tanto las respuestas de la Graph API como las notificaciones del webhook "messages". Esto te permitirá identificar y resolver cualquier inconveniente de manera eficiente.
Al profundizar en la integración, es clave entender los errores relacionados con plantillas y parámetros, ya que son de los más comunes al usar la API de WhatsApp Business. Estos errores suelen surgir cuando las plantillas no cumplen con los requisitos establecidos por Meta o cuando los valores dinámicos no coinciden con la estructura aprobada. Cada cuenta de WhatsApp Business puede tener un máximo de 250 plantillas aprobadas, y cada una debe pasar por un proceso de revisión que puede durar desde unos minutos hasta 24 horas.
Las plantillas incluyen varias secciones: un encabezado (que puede ser texto o multimedia), un cuerpo (con un máximo de 1.024 caracteres), un pie de página y hasta tres botones. También incorporan variables dinámicas, como {{1}} o {{2}}, que deben coincidir perfectamente con la cantidad de parámetros enviados en la solicitud a la API.
A continuación, se detallan los códigos de error más comunes y sus causas.
Otros errores frecuentes incluyen:
Conocer y comprender estos códigos permite validar y ajustar las plantillas para evitar interrupciones en la comunicación.
Para evitar rechazos, es importante no colocar variables al inicio o al final del cuerpo de la plantilla, ya que esto genera el error 2388299. Además, es recomendable mantener un equilibrio entre texto estático y variables, ya que un mensaje demasiado corto con muchas variables puede activar el error 2388293.
Cuando envíes plantillas para aprobación, asegurate de incluir ejemplos reales que muestren cómo se reemplazarán las variables dinámicas. Esto facilita que Meta valide el contenido.
También es esencial verificar que el nombre de la plantilla y el código de idioma (por ejemplo, es_AR) coincidan exactamente con la versión aprobada en el Administrador de WhatsApp Business. Además, los números de teléfono deben estar en formato E.164 para evitar errores relacionados con parámetros inválidos.
Por último, monitoreá la calificación de calidad de tus plantillas. Si los usuarios las reportan o bloquean con frecuencia, Meta podría pausarlas (error 132015) o deshabilitarlas (error 132016).
Burbuxa utiliza su sistema "Commerce Brain" para monitorear errores de API, integrando inteligencia artificial y automatizaciones en tiempo real. Esta conexión constante entre WhatsApp, Instagram y tu plataforma de e-commerce (ya sea Shopify, Tiendanube, VTEX o una API personalizada) permite identificar problemas de sincronización antes de que afecten la experiencia de tus clientes.
El sistema supervisa eventos clave de WhatsApp, como message_template_quality_update y message_template_status_update, para asegurar que tus plantillas mantengan una calificación "Alta" y sigan activas. Además, emplea "smart spacing" y estrategias de caché para prevenir errores HTTP 429, lo que resulta crucial en momentos de alto tráfico, como durante el Hot Sale, garantizando que las operaciones no se detengan.
Otra herramienta clave es el monitoreo sintético, que simula procesos como agregar productos al carrito o realizar el checkout para detectar fallas antes de que afecten a los usuarios. En casos más complejos, como discrepancias de precios o reembolsos de alto valor, el sistema activa el modo supervisado, donde la IA propone soluciones que deben ser aprobadas por un agente humano. Esto combina la velocidad de la automatización con la seguridad del control humano. Estas estrategias se integran con prácticas recomendadas para minimizar errores comunes.
| Práctica recomendada | Problema evitado | Beneficio con integración Burbuxa |
|---|---|---|
| Smart Spacing & Caché | HTTP 429 (límite de tasa) | Operación continua incluso en eventos de alto tráfico como Hot Sale. |
| Sincronización de inventario en tiempo real | Sobreventa o errores de stock agotado | Asegura un 99,9% de precisión entre el ERP y el catálogo de WhatsApp. |
| Monitoreo de calidad de plantillas | Plantillas pausadas o rechazadas | Mantiene la calificación "Alta", esencial para escalar niveles de mensajería. |
| Modo IA supervisado | Decisiones erróneas de IA o reembolsos incorrectos | Agrega un nivel de seguridad humana en tareas críticas. |
| Contexto entre canales | Frustración del cliente o consultas repetitivas | Permite transiciones fluidas entre Instagram y WhatsApp sin perder historial. |
Podés configurar alertas a través de Slack, email o WhatsApp para monitorear métricas críticas, como aumentos repentinos en el abandono del checkout o tasas de error en la API. Además, es importante revisar semanalmente la "Calificación de Calidad" en el Administrador de WhatsApp. Mantener un estado verde es clave para asegurar notificaciones proactivas y evitar que Meta pause tus plantillas.
Manejar errores de API en WhatsApp Business no se trata solo de cuestiones técnicas; es crucial para proteger tu operación de e-commerce y garantizar una experiencia fluida para tus clientes. Como vimos anteriormente, usar la API oficial y verificar correctamente tu Meta Business Manager son pasos clave para evitar bloqueos y cumplir con las políticas de Meta.
La diferencia entre herramientas básicas y soluciones avanzadas es evidente. Mientras los chatbots simples requieren actualizaciones manuales y pueden provocar errores en el inventario, Burbuxa sincroniza en tiempo real tu catálogo con plataformas como Shopify, Tiendanube o VTEX. Esto elimina riesgos de sobreventa, reduce la frustración del cliente y permite que tu equipo se concentre en tareas más estratégicas.
Además, mantener una calificación "Alta" en WhatsApp es indispensable para escalar desde el Nivel 1 (1.000 clientes únicos cada 24 horas) hasta el Nivel 4 (sin límites). Supervisar continuamente la calidad de los mensajes y ajustar el ritmo de las solicitudes es fundamental para evitar errores como el HTTP 429, especialmente en eventos de alto tráfico como el Hot Sale.
Otro punto importante es combinar automatización con supervisión humana en decisiones críticas, como reembolsos o discrepancias de precios. Configurá alertas en Slack, email o WhatsApp para monitorear métricas clave, como tasas de error en la API o el aumento en el abandono del checkout. Esto te permitirá actuar antes de que los problemas afecten a tus clientes.
La clave está en anticiparse. Revisá semanalmente la calificación de calidad en el Administrador de WhatsApp, asegurate de mantener sincronizados en tiempo real inventarios y precios, y utilizá herramientas de monitoreo para detectar fallas antes de que impacten en tu operación. Implementá estas acciones desde ya para convertir a WhatsApp Business en un canal sólido que impulse tus ventas y fortalezca la relación con tus clientes.
Los errores sincrónicos aparecen en el momento en que se realiza la llamada directa a la API, como al intentar enviar un mensaje. Estos errores devuelven un código de error de forma inmediata.
Por otro lado, los errores por webhook se reciben como notificaciones automáticas cuando ocurre un evento, como un inconveniente en el estado de un envío.
La clave para diferenciarlos está en el origen del error: si aparece en la respuesta inmediata de la API, es sincrónico; si llega mediante una notificación del webhook, pertenece a esa categoría.
Cuando te enfrentas a errores de límite de tasa (códigos 429 o 130429) en la API de WhatsApp Business, la mejor práctica es implementar un mecanismo de reintento exponencial.
Esto significa que, en lugar de intentar acceder repetidamente a la API de forma inmediata, debes aumentar progresivamente el tiempo de espera entre cada intento. Este enfoque no solo evita sobrecargar la API, sino que también asegura que respetes las restricciones de uso establecidas.
Para que tus plantillas de mensajes sean aceptadas y funcionen sin problemas, es clave que sean relevantes, claras y que cumplan con las políticas de contenido de Meta. Asegurate de que cada plantilla sea aprobada antes de su uso y que respeten las normativas relacionadas con el consentimiento y el manejo de datos personales.
Además, mantené una comunicación de calidad evitando cualquier contenido que pueda ser considerado spam o engañoso. Usá las plantillas solo en contextos adecuados para garantizar una experiencia positiva tanto para los usuarios como para la plataforma.
