# Errores de WhatsApp API en Magic Chat: qué significa cada uno y cómo solucionarlo

> Guía de diagnóstico de WhatsApp API: token vencido, permisos, número no registrado, ventana de 24 horas, plantillas, pagos y mensajes que no llegan.

Categoría: WhatsApp y Magic Chat · Actualizado: 2026-11-04 · Fuente: https://www.magicfunnel.app/ayuda/errores-de-whatsapp-api

Cuando algo falla con tu WhatsApp, Magic Chat te muestra un aviso en español con un título, qué significa, los pasos para arreglarlo y, al final, el «Mensaje original de Meta» en inglés. Esta guía reúne todos esos avisos para que identifiques el tuyo y lo soluciones sin esperar a soporte. Si estás usando un asistente de IA, mándale el pantallazo del aviso: los textos de aquí están escritos tal como salen.

**Dónde está:** Menú lateral → Integraciones → WhatsApp Business API → tu número (Estado de la conexión) y Magic Chat → Historial

## Antes de empezar

- Tu número ya conectado a Magic Chat (si aún no lo conectas, sigue primero la guía para conectar WhatsApp).
- Acceso de administrador al negocio en Meta (business.facebook.com) por si hay que cambiar algo allá.

## Paso a paso

1. **Revisa el Estado de la conexión de tu número.** Entra a **Integraciones**, abre **WhatsApp Business API** y, en **Cuentas conectadas**, abre tu número. En **Estado de la conexión** pulsa **Comprobar conexión**: Magic Chat le pregunta a Meta y marca cada punto en verde o en rojo. Si todo está bien verás «Todo en orden: tu WhatsApp envía y recibe.»; si no, «Hay pasos pendientes. Revisa los que están en rojo.», y cada punto en rojo trae su **Cómo arreglarlo**.
   - _Lo que ves en pantalla:_ Una tarjeta con el número, la etiqueta Conectado y tres datos: **Calidad** (GREEN, YELLOW, RED o Sin datos), **Límite de envío** (250 / día, 1K / día, 10K / día, 100K / día o Ilimitado) y **Nombre público**. Debajo, el bloque Estado de la conexión con un semáforo por paso y los desplegables Datos de la conexión (para verificar en Meta) y Herramientas avanzadas.
2. **Prueba que envía.** En la misma tarjeta, en **Enviar mensaje de prueba**, escribe tu propio WhatsApp con código de país (ej. 573001234567) y envía. Si es la primera vez que le escribes a ese número, WhatsApp exige una plantilla aprobada: el aviso lo dice. Si te llega, el envío funciona.
   - _Lo que ves en pantalla:_ Un campo de número, un campo «Mensaje…» con el texto «Hola! Este es un mensaje de prueba desde Magic Funnel.» y el botón de enviar. Al salir bien aparece «Mensaje enviado correctamente».
3. **Prueba que recibe.** Desde otro WhatsApp escríbele a tu número de negocio. El mensaje debe aparecer en **Magic Chat → Inbox** en segundos. Si no llega, revisa el enrutamiento de conversaciones (está en la tabla de abajo) y, si conectaste con el asistente manual, el webhook.
   - _Lo que ves en pantalla:_ En Herramientas avanzadas hay además «Simular un mensaje entrante para verificar que el Inbox funciona (no pasa por Meta)». Si el simulado aparece y el real no, el problema está del lado de Meta, no de tu Inbox.
4. **Mira por qué falló un mensaje.** Abre **Magic Chat → Historial**. Arriba están los contadores Total, Enviados, Recibidos, Entregados, Leídos y **Fallidos**. Cada mensaje fallido trae el motivo de Meta; búscalo en la tabla **Si ves este mensaje** de esta guía.
   - _Lo que ves en pantalla:_ Pestañas de Magic Chat: Inbox, Enviar, Broadcast, Historial, Templates y Automatizar. En Historial, seis contadores de colores y la lista de mensajes con su estado.
5. **Identifica el aviso y sigue sus pasos.** Cada aviso de error tiene un título en negrita (por ejemplo «El token de acceso venció»), una explicación, los pasos numerados y un botón como **Ir a Usuarios del sistema** o **Abrir WhatsApp Manager**. Sigue los pasos en orden y luego vuelve a pulsar **Comprobar conexión** o **Refrescar calidad y límites desde Meta**.
   - _Lo que ves en pantalla:_ Un recuadro rojo con un ícono de alerta, el título, la explicación, una lista numerada, un botón de enlace y al final, en letra pequeña, «Mensaje original de Meta: …».
6. **Si nada de lo anterior lo resuelve, abre un ticket.** Toca tu nombre o tu foto arriba a la derecha y abre **Centro de soporte** para crear un ticket (categoría «Error técnico»). Pega el título del aviso y el «Mensaje original de Meta»: con eso el equipo lo resuelve mucho más rápido.

## Consejos

- Antes de tocar nada en Meta, pulsa **Comprobar conexión**: casi siempre dice exactamente qué falta.
- Guarda en un lugar seguro el PIN de verificación en dos pasos de tu número; Meta lo pide para registrarlo.
- No uses el mismo número en la app de WhatsApp del celular y en la API al mismo tiempo.
- Si cambias de tarjeta en Meta, revisa que quede como método de pago de la cuenta de WhatsApp, no solo de la cuenta publicitaria.

## Si ves este mensaje

### «El token de acceso venció (Meta: "Error validating access token: Session has expired", código 190)»

**Qué significa:** El token que pegaste era temporal: los de la pantalla «Configuración de la API» de Meta Developers duran 24 horas. Cuando vence, WhatsApp se desconecta.

**Qué hacer:** Si conectaste con el botón Conectar con Facebook, vuelve a pulsarlo y repite la conexión. Si usaste el asistente manual, genera un token PERMANENTE: Meta Business → Configuración del negocio → Usuarios → Usuarios del sistema → tu usuario (rol Administrador) → Asignar activos → Cuentas de WhatsApp → Control total → Generar token, elige tu app, vencimiento Nunca, marca whatsapp_business_messaging y whatsapp_business_management, copia el token completo y pégalo en Canales.

### «El token de acceso no es válido (Meta: "Invalid OAuth access token" o "Malformed access token")»

**Qué significa:** Meta no reconoce el token: le falta o le sobra un carácter al copiarlo, o se revocó.

**Qué hacer:** Vuelve a copiar el token completo (empieza por EAA y es muy largo, sin espacios al principio ni al final) o genera uno nuevo desde Usuarios del sistema como se explica arriba.

### «Meta no reconoce este ID con tu token (Meta: "Unsupported get request. Object with ID '…' does not exist, cannot be loaded due to missing permissions")»

**Qué significa:** En 9 de cada 10 casos el ID está bien, pero el usuario del sistema que generó el token no tiene asignada tu cuenta de WhatsApp.

**Qué hacer:** Usuarios del sistema → tu usuario → Asignar activos → Cuentas de WhatsApp → marca tu cuenta → Control total → Guardar. Luego genera el token otra vez. Revisa también que el Phone Number ID sea el «Identificador del número de teléfono» (15–16 dígitos, no tu número de teléfono) y que el WABA ID sea el «Identificador de la cuenta de WhatsApp Business».

### «Al token le faltan permisos (Meta: "(#10) Application does not have permission for this action" o "(#200) Permissions error")»

**Qué significa:** El token es válido, pero al generarlo no marcaste los permisos de WhatsApp o el usuario no tiene acceso a la cuenta.

**Qué hacer:** Usuarios del sistema → Generar token → marca whatsapp_business_messaging y whatsapp_business_management, confirma que la cuenta de WhatsApp está asignada con Control total y pega el token nuevo.

### «Meta bloqueó el acceso a la API de tu app (Meta: "API access blocked", código 368)»

**Qué significa:** La app de Meta Developers con la que generaste el token está restringida, casi siempre porque Meta pidió el «Data Use Checkup» (revisión anual de uso de datos) y no se completó.

**Qué hacer:** Meta Developers → Mis apps → tu app: completa el Data Use Checkup si aparece pendiente (tarda unos 5 minutos). Si la app dice Restringida, sigue la apelación que indica Meta. Revisa también Configuración del negocio → Centro de seguridad.

### «El número no está registrado en la Cloud API (Meta: "Phone number is not registered", código 133010)»

**Qué significa:** Meta conoce el número, pero no está activado para enviar y recibir por la API.

**Qué hacer:** Escribe el PIN de 6 dígitos de la verificación en dos pasos del número y vuelve a conectar. Si lo olvidaste, restablécelo en Meta Developers → WhatsApp → Configuración de la API → Verificación en dos pasos.

### «El PIN de verificación en dos pasos no coincide (códigos 133005, 133008, 133009)»

**Qué significa:** El PIN que escribiste no es el que tiene el número.

**Qué hacer:** Revisa el PIN de 6 dígitos o restablécelo en Meta. Si lo intentaste varias veces seguidas, espera unos minutos: Meta bloquea por un rato.

### «Pasaron más de 24 horas desde el último mensaje del cliente (Meta: "Re-engagement message", código 131047)»

**Qué significa:** Regla de WhatsApp: el texto libre solo se puede enviar dentro de las 24 horas siguientes al último mensaje que te mandó la persona.

**Qué hacer:** Envíale una plantilla aprobada (en el chat: botón Enviar plantilla aprobada). Cuando te responda, la ventana se abre otras 24 horas y puedes escribirle normal.

### «No se pudo entregar el mensaje a ese número (Meta: "Message undeliverable", códigos 131026 o 131021)»

**Qué significa:** El número no tiene WhatsApp, está mal escrito o bloqueó a tu negocio.

**Qué hacer:** Escribe el número con código de país, sin espacios, signos ni el 0 inicial (ej. 573001234567, 5215512345678, 51987654321). Confirma con la persona que ese número tiene WhatsApp.

### «Esta persona te escribe con su nombre de usuario de WhatsApp, sin número visible»

**Qué significa:** Algunas personas usan un nombre de usuario de WhatsApp y Meta no comparte su número. Se le puede contestar con el identificador que manda WhatsApp cuando escribe.

**Qué hacer:** Espera a que vuelva a escribir y contéstale desde esa conversación. No intentes escribirle desde Enviar con un número.

### «La plantilla no existe o no está aprobada (Meta: "Template name does not exist in the translation", código 132001)»

**Qué significa:** Meta no encuentra una plantilla con ese nombre e idioma en tu cuenta, o sigue en revisión.

**Qué hacer:** En Magic Chat → Templates revisa que esté en Aprobado y que el idioma sea el mismo con el que la envías (es, es_MX, en_US…). Solo se envían plantillas aprobadas.

### «Los parámetros de la plantilla no coinciden (códigos 132000, 132005, 132012)»

**Qué significa:** La plantilla espera un número de variables distinto, o un valor tiene saltos de línea, tabulaciones o muchos espacios seguidos.

**Qué hacer:** Cuenta las variables {{1}}, {{2}}… de la plantilla y llena exactamente esa cantidad. Dentro de una variable no pongas saltos de línea.

### «La plantilla está pausada o deshabilitada (códigos 132015 y 132016)»

**Qué significa:** Meta pausó la plantilla porque mucha gente la bloqueó o la reportó.

**Qué hacer:** Revisa su estado en WhatsApp Manager → Plantillas de mensajes. Si sigue pausada, crea una nueva con otro texto más útil y personal.

### «Hay un problema con tu cuenta de WhatsApp Business en Meta (código 131042: método de pago)»

**Qué significa:** Meta exige un método de pago activo para cobrarte las plantillas, o hay un problema de elegibilidad del negocio.

**Qué hacer:** Business Suite → Facturación y pagos → Cuentas de WhatsApp Business → agrega o corrige la tarjeta. Revisa las notificaciones de WhatsApp Manager.

### «Hay un problema con tu cuenta de WhatsApp Business en Meta (código 131031: cuenta bloqueada)»

**Qué significa:** Meta bloqueó la cuenta temporalmente por una infracción de políticas o actividad sospechosa.

**Qué hacer:** Abre WhatsApp Manager y Business Suite → Centro de seguridad, lee la notificación y, si es un error, solicita la revisión desde ahí.

### «El nombre para mostrar aún no está aprobado (código 131037)»

**Qué significa:** Meta revisa el nombre público del número antes de dejarlo enviar.

**Qué hacer:** Espera la aprobación en WhatsApp Manager → Números de teléfono. Si lo rechazaron, cámbialo para que coincida con el nombre de tu negocio o tu marca.

### «Límite de envíos alcanzado (Meta: "Rate limit hit", códigos 4, 80007, 130429)»

**Qué significa:** Meta está frenando por un rato porque se superó el límite de mensajes por hora o por día de tu número.

**Qué hacer:** Espera unos minutos. Si te pasa seguido, revisa tu Límite de envío y tu Calidad (guía «Salud y límites de tu número de WhatsApp»).

### «El destinatario no está en la lista de prueba (código 131030)»

**Qué significa:** Estás usando el número de prueba gratuito de Meta, que solo puede escribirle a los teléfonos de la lista «Para».

**Qué hacer:** Conecta tu propio número. Mientras pruebas, agrega el teléfono en Meta Developers → WhatsApp → Configuración de la API → Administrar lista de números de teléfono.

### «Mi número envía pero no recibe (en Meta: "another app is controlling this thread", código 131070)»

**Qué significa:** Las conversaciones de tu número están enrutadas a otra app o a la bandeja de Business Suite, no a Magic Funnel.

**Qué hacer:** business.facebook.com → WhatsApp Manager → Cuentas de WhatsApp → tu número → pestaña Conversation routing (Enrutamiento de conversaciones). Cambia todas las filas de Message routing a Magic Funnel. Los chats nuevos entran al instante; los que ya existían pueden quedarse con el destino viejo hasta que se cierren.

### «Meta tuvo un error temporal (códigos 1, 2, 131000, 131016)»

**Qué significa:** No es un problema de tu configuración: los servidores de Meta respondieron con un error pasajero.

**Qué hacer:** Espera 1 o 2 minutos y vuelve a intentarlo.

### «No se pudo cargar Facebook / No se pudo abrir Facebook. Revisa si tienes un bloqueador de anuncios activo.»

**Qué significa:** El navegador bloqueó la ventana oficial de Meta que usa el botón Conectar con Facebook.

**Qué hacer:** Desactiva el bloqueador de anuncios para magicfunnel.app, permite ventanas emergentes y vuelve a intentarlo. Usa Chrome o Safari actualizados, no la vista dentro de Instagram o de WhatsApp.

### «Cerraste la ventana de Meta antes de terminar.»

**Qué significa:** La conexión quedó a medias porque la ventana de Meta se cerró antes del último paso.

**Qué hacer:** Pulsa otra vez Conectar con Facebook y sigue hasta que la ventana se cierre sola y aparezca «¡Tu WhatsApp quedó conectado!».

### «Conectar WhatsApp API es parte de los planes. Activa Glow para conectar tu primer número.»

**Qué significa:** Tu cuenta está en el plan Gratis, que no incluye WhatsApp API.

**Qué hacer:** Pulsa Ver planes y activa un plan: Glow incluye 1 número, Flash 2 y Nova 3.

### «Tu plan incluye N números de WhatsApp. Cada número adicional cuesta 40 créditos al mes.»

**Qué significa:** Ya usaste los números que incluye tu plan; el siguiente es un número adicional.

**Qué hacer:** Confirma el cobro de 40 créditos al mes para conectarlo, o desconecta un número que ya no uses. Si un mes no tienes créditos, ese número se pausa y te llega «Pausamos un número de WhatsApp ⏸️» en la campana.

## Preguntas frecuentes

### ¿Cómo le muestro el error a ChatGPT u otro asistente?

Toma un pantallazo del recuadro rojo completo, incluida la línea «Mensaje original de Meta», y del bloque Estado de la conexión con sus semáforos. Con el título del aviso y ese mensaje el asistente encuentra la solución en esta guía.

### Todo sale en verde pero un contacto no recibe mis mensajes, ¿por qué?

Revisa el estado del mensaje en Historial. Si dice Fallido con el código 131047, pasaron más de 24 horas y necesitas una plantilla; si dice 131026, el número está mal escrito o no tiene WhatsApp; si dice Entregado pero no Leído, el mensaje sí llegó y la persona no lo ha abierto.

### ¿Por qué de repente se desconectó mi WhatsApp?

Las causas más comunes son un token temporal que venció (24 horas), que alguien quitó el acceso del usuario del sistema en Meta, que el número se registró de nuevo en la app del celular o que Meta restringió la app. Pulsa Comprobar conexión: el punto en rojo te dice cuál fue.

### ¿Los mensajes fallidos se cobran?

Meta solo cobra las plantillas que entrega. Un mensaje que falla antes de entregarse no se cobra.

## Relacionado

- [Cómo conectar tu WhatsApp a Magic Chat con la API oficial de Meta](https://www.magicfunnel.app/ayuda/conectar-whatsapp-magic-chat)
- [Cómo crear plantillas de WhatsApp y que Meta las apruebe](https://www.magicfunnel.app/ayuda/plantillas-de-whatsapp)
- [Salud y límites de tu número de WhatsApp: calidad, límite de envío y nombre público](https://www.magicfunnel.app/ayuda/salud-y-limites-de-tu-numero-de-whatsapp)
- [Cómo atender tus conversaciones en la bandeja de Magic Chat](https://www.magicfunnel.app/ayuda/bandeja-de-magic-chat)
- [Problemas frecuentes en Magic Funnel y cómo pedir ayuda al soporte](https://www.magicfunnel.app/ayuda/problemas-frecuentes-y-soporte)
