Errores de la API de WhatsApp: códigos más comunes y cómo resolverlos

Actualizado el 25/10/2026

El error 131047 de la API de WhatsApp significa que pasaron más de 24 horas desde el último mensaje del cliente, así que la ventana de atención al cliente se cerró y ya no se aceptan mensajes de texto libre. La solución es enviar una plantilla aprobada. Los demás códigos comunes siguen la misma lógica: cada uno indica una causa (destinatario, límite, plantilla, cuenta o token) y una acción, y Meta recomienda manejar el error por code, no por el estado HTTP.

Esta guía reúne los códigos que más aparecen en producción, todos verificados en la tabla oficial de códigos de error de Meta, y muestra cómo separar lo que se puede reintentar de lo que no se debe reenviar.

Dónde aparecen los errores

La Cloud API devuelve errores en dos lugares, y a veces en ambos:

• En la respuesta sincrónica de la llamada de envío, cuando el problema se detecta en el momento: token inválido, parámetro incorrecto, plantilla inexistente, límite de llamadas.
• En el webhook messages, de forma asincrónica, cuando el mensaje fue aceptado pero no se pudo entregar. En ese caso llega un estado failed con el arreglo errors.

Por eso no basta con el 200 OK del envío. Un mensaje aceptado por la API puede fallar minutos después. El artículo sobre estados de mensaje por webhook explica cómo guardar esos eventos.

Formato del error sincrónico

{
  "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"
  }
}

Los campos que importan:

• code: el número que usa tu lógica. Meta recomienda construir el manejo de errores sobre él.
• error_data.details: la explicación más específica, a veces con la corrección sugerida. Guárdalo siempre en el log.
• fbtrace_id: identificador para abrir un ticket con el soporte de Meta.
• error_subcode: obsoleto; no se devuelve desde la versión 16.0 de la API.

Formato del error en el webhook

Cuando falla la entrega, el evento de estado trae el mismo code. Este es el ejemplo de la documentación oficial, con el error 131049:

{
  "statuses": [
    {
      "id": "wamid.HBgLNTU4NDk5OTk5OTk5...",
      "status": "failed",
      "timestamp": "1761400000",
      "recipient_id": "5584999999999",
      "errors": [
        {
          "code": 131049,
          "title": "This message was not delivered to maintain healthy ecosystem engagement.",
          "message": "This message was not delivered to maintain healthy ecosystem engagement.",
          "error_data": {
            "details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
          },
          "href": "/documentation/business-messaging/whatsapp/support/error-codes"
        }
      ]
    }
  ]
}

Los errores que no están ligados a un mensaje específico pueden llegar en entry.changes.value.errors.

Los códigos más comunes y qué hacer

Código	Qué significa	Qué hacer
131047	Más de 24 horas desde la última respuesta del cliente	Enviar una plantilla aprobada
131026	Mensaje no entregable: el destinatario no usa WhatsApp, no aceptó los términos vigentes o usa una versión antigua de la app	Confirmar el número por otro canal; no reintentar en bucle
131049	Mensaje de marketing no entregado para mantener un engagement saludable (límite por usuario)	Esperar al menos 24 horas antes de reenviar
131050	El destinatario dejó de recibir mensajes de marketing de la empresa	No reenviar; marcar como opt-out
131056	Demasiados mensajes del mismo número al mismo destinatario en poco tiempo	Esperar y reintentar para ese destinatario
130429	Se alcanzó el límite de rendimiento (throughput) de la Cloud API	Bajar el ritmo y reintentar con espera creciente
131048	Envío restringido porque mensajes anteriores fueron bloqueados o marcados como spam	Revisar la calidad en el Administrador de WhatsApp
130472	Mensaje no enviado por formar parte de un experimento de mensajes de marketing	Ver la documentación del experimento; no es un fallo de tu código
131042	Problema con el método de pago	Revisar la cuenta de pago, límite de crédito, moneda y zona horaria
131051	Tipo de mensaje no admitido	Usar un tipo que la API acepte
131053	No se pudo subir el archivo multimedia del mensaje	Revisar el tipo MIME y el formato del archivo
131000	Error desconocido	Reintentar; si persiste, abrir un ticket
131016	Servicio no disponible temporalmente	Ver la página de estado de la plataforma y reintentar

131047: la ventana de 24 horas está cerrada

Aparece cada vez que alguien intenta enviar texto libre, una imagen o botones a un contacto que no le escribió a la empresa en las últimas 24 horas. Cada mensaje del cliente abre la ventana de atención. Fuera de ella, solo plantillas.

La corrección tiene dos partes. En el código, antes de enviar, verifica cuándo llegó el último mensaje de ese wa_id y usa una plantilla si pasaron más de 24 horas. En el producto, usa una plantilla de utilidad o de marketing para retomar la conversación: cuando el cliente responde, la ventana se abre de nuevo.

131026: mensaje no entregable

Meta enumera tres causas: el número no tiene WhatsApp, la persona no aceptó los términos o la política de privacidad más recientes, o usa una versión antigua de la aplicación. La API no dice cuál de las tres ocurrió. Reenviar el mismo mensaje no lo resuelve. Marca el contacto, pide confirmación por otro canal (correo, SMS) y revisa el origen de tu base: un número mal escrito cae en el primer caso.

131049 y 131050: límites de marketing

El 131049 es el límite por usuario de plantillas de marketing: Meta retiene el mensaje para no saturar a quien ya recibe mucho marketing. La indicación oficial es esperar al menos 24 horas antes de reintentar. Reenviar enseguida solo genera otro fallo. El tema tiene un artículo propio: límite de marketing por usuario.

El 131050 es distinto: la persona eligió dejar de recibir marketing de tu empresa. No reenvíes. Trátalo como opt-out y, si quieres seguir esos cambios, suscríbete al webhook user_preferences.

131056 y 130429: ritmo de envío

El 131056 es un límite por par de números: demasiados mensajes de tu número al mismo destinatario en poco tiempo. Los demás destinatarios no se ven afectados, así que solo esa cola tiene que esperar.

El 130429 es el límite de throughput del número. Distribuye el envío en el tiempo y reintenta con espera exponencial.

¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →

Errores de plantilla (132xxx)

Código	Qué significa	Qué hacer
132000	La cantidad de variables enviadas no coincide con la plantilla	Enviar un valor para cada variable
132001	La plantilla no existe en ese idioma o no está aprobada	Revisar nombre, código de idioma (ej.: es_MX) y estado
132005	El texto traducido es demasiado largo	Acortar la traducción en el Administrador de WhatsApp
132007	El contenido de la plantilla infringe una política de WhatsApp	Revisar el texto y volver a enviarla
132012	Los valores de las variables no tienen el formato esperado	Ajustar al formato definido (ej.: multimedia en el encabezado)
132015	Plantilla pausada por baja calidad	Editar la plantilla y esperar la aprobación
132016	Plantilla pausada demasiadas veces y desactivada de forma permanente	Crear una plantilla nueva con contenido distinto
132068	Flow bloqueado	Corregir el Flow
132069	Flow limitado: ya se enviaron 10 mensajes con él en la última hora	Corregir el Flow

El 132001 suele ser un error de tipeo: es_mx en lugar de es_MX, una mayúscula en el nombre o una plantilla todavía en revisión. El 132000 aparece cuando alguien edita la plantilla y olvida actualizar el código que arma los parameters. Los Flows se explican en WhatsApp Flows.

Errores de token, permisos y cuenta

Código	Qué significa	Qué hacer
0	No se pudo autenticar al usuario de la app (token vencido o invalidado)	Generar un token nuevo
190	Token de acceso vencido	Generar un token nuevo
3 y 10	Permiso ausente o retirado	Revisar los permisos en el depurador de tokens
100	Parámetro no admitido o mal escrito	Comparar con la referencia del endpoint
4	Se alcanzó el límite de llamadas de la app	Reducir la frecuencia de llamadas
80007	Se alcanzó el límite de llamadas de la cuenta de WhatsApp Business (WABA)	Reducir la frecuencia de llamadas
368	Cuenta restringida o desactivada por infringir políticas	Revisar la aplicación de políticas y resolver la infracción
131031	Cuenta bloqueada, o el dato enviado no coincide (ej.: PIN de dos pasos incorrecto)	Consultar la Health Status API
131037	Número 555 sin nombre visible aprobado	Aprobar el nombre visible
133010	Número no registrado en la plataforma	Registrar el número y reintentar

Si los errores 0 y 190 aparecen seguido, el problema casi siempre es el tipo de token. Los tokens temporales vencen; para producción, usa un token permanente de usuario del sistema.

Una advertencia sobre códigos antiguos: algunas listas que circulan en internet todavía mencionan el código 470. No aparece en la tabla actual de la Cloud API. Si tu sistema todavía maneja el 470, revísalo y pasa a usar los códigos actuales.

Cómo manejar los errores en el código

La regla práctica es separar tres grupos: lo que se resuelve con un reintento, lo que requiere otro tipo de mensaje y lo que no se debe reenviar.

// Clasifica el error de la Cloud API por code
const RETRY = new Set([130429, 131056, 131000, 131016, 4, 80007]);
const USE_TEMPLATE = new Set([131047]);
const WAIT_24H = new Set([131049]);
const DO_NOT_RETRY = new Set([131026, 131050, 132001, 132007, 132015, 132016, 368]);

function decide(code) {
  if (RETRY.has(code)) return 'retry_with_backoff';
  if (USE_TEMPLATE.has(code)) return 'send_template';
  if (WAIT_24H.has(code)) return 'retry_after_24h';
  if (DO_NOT_RETRY.has(code)) return 'stop_and_flag';
  return 'log_and_review';
}

function onStatus(status) {
  if (status.status !== 'failed') return;
  for (const err of status.errors || []) {
    const action = decide(err.code);
    console.log(status.id, status.recipient_id, err.code, err.error_data?.details, action);
  }
}

Tres cuidados:

1. Espera creciente en los reintentos. Para 130429 y 131056, reintenta después de 1, 2, 4, 8 segundos, con un tope. Reintentar sin esperar empeora el límite.
2. Guarda code, details y fbtrace_id. Sin eso, el ticket con Meta no avanza.
3. Meta solo cobra los mensajes entregados. Aun así, cada fallo de entrega en marketing puede indicar un problema de base o de calidad. Sigue la tasa de failed por código a lo largo del tiempo.

Cómo funciona con Vectalk

En Vectalk, los webhooks son los mismos de Meta: el estado failed llega con el arreglo errors y los mismos códigos de esta tabla, así que el mismo manejo sirve. Los errores de autenticación propios de Vectalk son 401 (token ausente, inválido o revocado) y 403 (token sin permiso para ese recurso, como un token de organización llamando a un endpoint que exige token de instancia), documentados en Autenticación. También puedes filtrar el historial por status=failed con el endpoint Listar Mensajes para revisar los fallos.

Para empezar, crea tu cuenta en apps.vectalk.com.br/register.

Preguntas frecuentes

¿Qué es el error 131047 de WhatsApp?

Es el error de «reactivación»: el mensaje no se envió porque pasaron más de 24 horas desde la última respuesta del cliente. Fuera de la ventana de atención, solo se pueden enviar plantillas aprobadas.

¿El error 131026 significa que el número no tiene WhatsApp?

Puede significarlo, pero no solo eso. Meta también menciona a un usuario que no aceptó los términos más recientes y una versión desactualizada de la app. La API no indica cuál de las causas ocurrió.

¿Se cobran los mensajes con error?

Meta indica que cobra solo los mensajes entregados, no los enviados. Un mensaje que termina en failed nunca se entregó.

¿Debo reenviar los mensajes con error 131049?

Solo después de al menos 24 horas, como recomienda Meta. Si reenvías antes, lo más probable es que vuelva a fallar.

¿Dónde encuentro la lista completa de códigos?

En la página Error codes de la documentación de Meta, que también incluye errores de creación de plantillas, migración de números y de la Marketing Messages API.

---

Fuentes oficiales consultadas el 25/10/2026: Códigos de error de la WhatsApp Cloud API, Referencia del webhook de estados, Precios de la plataforma de WhatsApp Business, Documentación de Vectalk: Autenticación, Documentación de Vectalk: Listar Mensajes.