Errores de WhatsApp Business API: qué significa cada código y cómo resolverlo

Un error de la Cloud API es un objeto JSON con un código numérico y una descripción de la causa. Puede llegar en la respuesta inmediata a tu solicitud (síncrono), después en el webhook messages (asíncrono) o por las dos vías, así que Meta recomienda vigilar ambas. Este es el ejemplo que publica Meta:

{
  "error": {
    "message": "(#130429) Rate limit hit",
    "type": "OAuthException",
    "code": 130429,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Cloud API message throughput has been reached."
    },
    "fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}

En los webhooks, los errores generales llegan en entry.changes.value.errors y los de cada mensaje o estado, dentro de ese mensaje o estado. Un estado failed trae un arreglo errors con code, title, message, error_data.details y href (el enlace a la página de códigos). Qué significa cada estado: estados de mensajes y webhooks.

Estos son los códigos que más aparecen al enviar mensajes con la Cloud API. Cada uno tiene su detalle (causa y solución) en la tabla de su familia, más abajo.

Son errores de acceso: el token o los permisos no alcanzan, o Meta restringió la cuenta. Ninguno se resuelve reintentando la misma solicitud.

368 y 131031 comparten causa: la cuenta asociada a la app fue restringida o deshabilitada por incumplir una política. 131031 tiene un segundo significado, más técnico: Meta no pudo verificar un dato de tu solicitud contra la cuenta, como un PIN de verificación en dos pasos incorrecto. Las restricciones crecen con cada reincidencia: bloqueo de 1 o 3 días para enviar plantillas de marketing, utility y authentication; de 5, 7 o 30 días para enviar cualquier mensaje; bloqueo de cuenta que solo se levanta con una apelación, y deshabilitación permanente.

La apelación se pide en Business Support Home y la decisión suele tardar de 24 a 48 horas. Para enterarte de una infracción en tiempo real, con el tipo y la duración de la restricción, suscríbete al webhook account_update. El paso a paso para apelar está en cómo recuperar una cuenta bloqueada.

Son errores de ritmo o de volumen: Meta frena el envío porque superaste un tope. Algunos se resuelven esperando unos segundos; otros, esperando 24 horas o cambiando la estrategia.

Cada código corresponde a un límite distinto: el de llamadas a la API (4 y 80007), el throughput de cada número (130429), el ritmo por par empresa–usuario (131056), el límite de marketing por usuario (131049) y las restricciones por calidad o por clasificación (131048 y 131064). El límite de mensajería (cuántos usuarios únicos puedes contactar fuera de la ventana de servicio en 24 horas móviles, fijado por business portfolio) no tiene un código propio en la lista de Meta: consulta tu nivel con el campo whatsapp_business_manager_messaging_limit o en la guía de límites de mensajes.

131047 significa que pasaron más de 24 horas desde la última respuesta del usuario: la ventana de servicio de 24 horas está cerrada y Meta rechaza el mensaje sin plantilla. La ventana se abre cuando el usuario te escribe o te llama, y vuelve a 24 horas con cada nuevo mensaje o llamada. Mientras está abierta puedes enviar cualquier mensaje de servicio; cuando se cierra, solo plantillas aprobadas. Reintentar el mismo texto no sirve: hay que enviar una plantilla.

No lo confundas con el Free Entry Point (FEP) de Click to WhatsApp. Son dos relojes distintos. El FEP es una exención de cobro: si respondes dentro de las 24 horas a quien llegó por un anuncio, durante hasta 7 días no se cobran Marketing, Utility, Authentication ni Servicio (Meta Business Agent sí se cobra). La ventana de 24 horas, en cambio, es el permiso para enviar texto libre. El FEP no amplía la ventana: si pasaron 24 horas desde el último mensaje del usuario, el texto libre devuelve 131047 aunque el FEP siga abierto. En ese caso envía una plantilla, que mientras dure el FEP no se cobra. Detalle en Click to WhatsApp: hasta 7 días sin cobro.

Con Direct Send pasa lo mismo si no indicas una categoría: el mensaje sigue el flujo normal y, sin ventana abierta, devuelve 131047.

Si ves picos de 131047, revisa tu lógica de cola: normalmente son respuestas de agentes escritas horas después o automatizaciones que se disparan con retraso. Guarda la hora del último mensaje de cada usuario y decide antes de enviar si corresponde texto libre o plantilla.

Son errores sobre el destinatario o el contenido del envío: la solicitud puede ser válida, pero ese mensaje no puede llegar a esa persona. Casi ninguno se resuelve reintentando.

No hay un código para "el usuario bloqueó a tu empresa": ese mensaje queda en sent sin pasar a delivered y Meta no informa la causa. La guía de cómo saber si un cliente te bloqueó explica qué hacer.

135000 tiene dos lecturas. En la lista general es un error desconocido con los parámetros de la solicitud. Con el portfolio pacing (la entrega por lotes que Meta aplica a portfolios con menos de 500.000 plantillas enviadas en 365 días o bajo monitoreo), es el código de los mensajes retenidos como held_for_quality_assessment que Meta descarta al detectar señales sospechosas. En ese caso, además, el portfolio no puede enviar ni crear plantillas mientras dura la revisión.

Son errores de la plantilla que envías o que intentas crear: parámetros que no coinciden, idioma o estado incorrectos, pausas por calidad y reglas propias de Marketing Messages API y Direct Send.

Las pausas siguen una escala fija: la primera dura 3 horas, la segunda 6 horas y la tercera deshabilita la plantilla (132016). Intentar enviar una plantilla pausada no se cobra ni consume tu límite de mensajería, pero la API lo rechaza igual: frena las campañas que dependen de ella. Cómo reactivarlas y qué hacer después: plantillas pausadas.

132000 y 132001 se detectan rápido en un ambiente de pruebas: envía siempre una plantilla de cada tipo antes de liberar un cambio a producción, sobre todo si editaste la plantilla o la reutilizas en otro idioma.

WhatsApp Flows tiene sus propios códigos: dos que devuelve la Cloud API al enviar (132068 y 132069), los de la API de gestión de Flows (139000 a 139006) y los que genera tu endpoint o llegan como alertas por webhook.

Si usas un endpoint, dos errores generales también se aplican a Flows: el 10, si el número con el que configuraste la clave pública no está habilitado, y el 100, si la clave no es una clave pública RSA de 2048 bits en formato PEM. Más sobre cómo se arman y se publican: guía de WhatsApp Flows.

Aparecen al registrar o dar de baja un número en la Cloud API, al migrarlo o al sincronizar un número de la App conectado a la API (Coexistence). El registro solo se hace por API, con un pin de 6 dígitos, no desde WhatsApp Manager.

El límite que más sorprende es el de 133016: los endpoints de registro y de baja admiten 10 solicitudes por número en 72 horas móviles, y al pasarte el número queda bloqueado para esa operación durante las 72 horas siguientes. No automatices reintentos de registro. Tampoco puedes dar de baja por API un número que se usa a la vez en la App y en Cloud API. Y con el nuevo modelo de cuentas, la migración de números entre cuentas no está soportada: si cambias de proveedor, compartes la WhatsApp account.

Meta está retirando el PIN de los números elegibles. La guía de verificación en dos pasos explica cómo saber si tu número todavía lo usa y qué enviar en pin mientras tanto.

Son errores de la cuenta de pago de tu Messaging account o de los términos de los pagos dentro del chat. Se corrigen en la configuración de facturación, no en el código.

Un mensaje que no se entrega no se cobra: Meta cobra por mensaje entregado. Tampoco se cobra el intento de enviar una plantilla pausada ni el mensaje que no sale por el experimento de marketing (130472). Qué cambió en la facturación de Meta: cambio de precios de octubre de 2026.

Los webhooks traen los errores asíncronos de tus envíos y también algunos de los mensajes que recibes. Si tu endpoint falla, además, pierdes la señal de todos los demás errores.

Meta reintenta los webhooks que no reciben un 200 con frecuencia decreciente durante hasta 7 días, y esos reintentos pueden llegar duplicados: responde 200 rápido, procesa en una cola y descarta duplicados por ID. Los payloads pesan hasta 3 MB. Si filtras por IP, ten en cuenta que Meta cambia sus direcciones periódicamente; como alternativa, sugiere usar mTLS.

La Health Status API te dice, antes de enviar, si un número, una plantilla o una cuenta pueden mandar mensajes. Se consulta pidiendo el campo health_status sobre la Messaging account (WABA), el número de empresa o la plantilla:

GET /<NODE_ID>?fields=health_status

La respuesta resume todos los nodos que intervienen en el envío: el número (si consultaste un número), la plantilla (si consultaste una plantilla), la Messaging account, el business portfolio y la app. Cada uno tiene un valor can_send_message:

El can_send_message general toma el peor valor: BLOCKED si algún nodo está bloqueado, LIMITED si ninguno está bloqueado pero alguno está limitado y AVAILABLE solo si todos están disponibles. Para llamadas por SIP existe can_receive_call_sip, que no tiene valor general. Es el primer chequeo cuando recibes 131031: Meta indica que esta API puede dar más contexto sobre el bloqueo de la cuenta. Ejemplo de respuesta LIMITED (de la documentación de Meta):

{
  "health_status": {
    "can_send_message": "LIMITED",
    "entities": [
      {
        "entity_type": "PHONE_NUMBER",
        "id": "106540352242922",
        "can_send_message": "LIMITED",
        "additional_info": [
          "Your display name has not been approved yet. Your message limit will increase after the display name is approved."
        ]
      },
      { "entity_type": "WABA", "id": "102290129340398", "can_send_message": "AVAILABLE" },
      { "entity_type": "BUSINESS", "id": "506914307656634", "can_send_message": "AVAILABLE" },
      { "entity_type": "APP", "id": "634974688087057", "can_send_message": "AVAILABLE" }
    ]
  },
  "id": "106540352242922"
}

Depurar un error es pasar del código a la causa y de la causa a una acción. Este orden evita reintentos inútiles:

1. Guarda la respuesta completa. Registra code, error_data.details y fbtrace_id. No bases tu lógica en el título del error ni en el código HTTP.
2. Escucha el webhook, no solo la respuesta. Un 200 al enviar solo dice que Meta aceptó la solicitud. Si después llega un estado failed, el arreglo errors trae el código real.
3. Ubica el código en su familia. Autorización, límites, envío, plantillas, Flows, registro, pagos o webhooks: la tabla de cada familia dice si conviene reintentar.
4. Consulta la Health Status API del número y, si envías una plantilla, de la plantilla. Si algo figura BLOCKED, no sigas enviando.
5. Revisa la ventana. Con 131047, la ventana de 24 horas está cerrada: usa una plantilla, aunque haya un Free Entry Point abierto.
6. Revisa la plantilla. Estado aprobado, calidad (quality_score), categoría, idioma y cantidad de variables.
7. Revisa los límites. Nivel de mensajería (whatsapp_business_manager_messaging_limit), throughput (GET /<PHONE_NUMBER_ID>?fields=throughput) y ritmo por usuario.
8. Revisa las sanciones. Business Support Home y el webhook account_update muestran infracciones y restricciones activas.
9. Descarta una caída en metastatus.com y, si el error persiste, abre un ticket en Direct Support con el fbtrace_id.

¿Cuándo conviene reintentar y cuándo no?