Códigos de error de WhatsApp Cloud API: causas y soluciones
Códigos de error de WhatsApp Cloud API explicados: qué significan 131047, 131026, 130429, 132001, 141010 y los demás, y si conviene reintentar.
Un código de error de WhatsApp es el número que Meta devuelve cuando la Cloud API rechaza una
llamada o no logra entregar un mensaje. Con Genuka WA, lo lees en el campo meta.code de la
respuesta de error, o en data.errors[].code del webhook de estado failed. Las tablas de abajo
indican, para cada código, qué significa y si conviene reintentar.
Última actualización: 8 de octubre de 2026
¿Qué códigos de error de WhatsApp se documentan aquí?
Las familias siguen la lista oficial de Meta (autorización, límites de velocidad, integridad, otros errores), y los "otros errores" se agrupan aquí por tema. Los mensajes de Meta se citan tal cual, en inglés, como llegan en las respuestas de la API.
Autorización y tokens de acceso
| Código | Mensaje de Meta | Qué significa | ¿Reintentar? |
|---|---|---|---|
| 0 | "We were unable to authenticate the app user." | El token de acceso expiró, fue invalidado o su propietario cortó el acceso de las aplicaciones. | No: hace falta un token nuevo. Con Genuka WA ese token es nuestro: contacta al soporte. |
| 3 | "Capability or permissions issue." | La aplicación no tiene la capacidad o el permiso que exige este endpoint concreto. | No: otorga el permiso que falta. |
| 10 | "Permission is either not granted or has been removed." | Falta un permiso. Caso frecuente: una plantilla OTP para una empresa que Meta no ha verificado. | No. |
| 190 | "Your access token has expired." | El token de acceso expiró o ya no es válido. | No: reemplaza el token. Con Genuka WA nunca manejas un token de Meta. |
| 200 | "Permission is either not granted or has been removed." (rango 200 a 299) | Token ausente, permiso revocado o un usuario del sistema sin acceso a la cuenta. No tiene nada que ver con el estado HTTP 200. | No: restablece el acceso. |
Límites de velocidad
| Código | Mensaje de Meta | Qué significa | ¿Reintentar? |
|---|---|---|---|
| 4 | "The app has reached its API call rate limit." | La aplicación completa superó su límite de llamadas a la API de Meta. | Sí, más tarde, con menos llamadas. |
| 80007 | "The WhatsApp Business Account has reached its rate limit." | Demasiadas llamadas de gestión (plantillas, números) sobre una misma cuenta de WhatsApp Business en una hora. | Sí, más tarde. |
| 130429 | "Cloud API message throughput has been reached." | El número envía más rápido que su capacidad de envío de mensajes. | Sí, con esperas crecientes. |
| 131048 | "Message failed to send because there are restrictions on how many messages can be sent from this phone number…" | Meta restringe los envíos del número tras demasiados bloqueos o reportes de spam. | Solo más tarde, una vez que hayas saneado tus envíos. |
| 131056 | "Too many messages sent from the sender phone number to the same recipient phone number in a short period of time." | Demasiados mensajes al mismo destinatario en poco tiempo. | Sí, a ese destinatario, después de una pausa. |
Integridad y estado de la cuenta
| Código | Mensaje de Meta | Qué significa | ¿Reintentar? |
|---|---|---|---|
| 368 | "The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy." | La cuenta de WhatsApp Business está restringida o desactivada por infringir una política de Meta. | No: solicita una revisión a Meta. |
| 141010 | "The Business has not passed business verification" | La empresa no ha superado la verificación de Meta, así que sus plantillas OTP se rechazan. Este código aparece en el estado de salud de la cuenta (health_status), no en la lista de códigos de error de Meta. | No: haz verificar la empresa. |
Solicitud y número de teléfono
| Código | Mensaje de Meta | Qué significa | ¿Reintentar? |
|---|---|---|---|
| 33 | "The business phone number has been deleted." | El ID de número de teléfono que usas ya no apunta a un número activo. | No: verifica el ID y vuelve a conectar el número. |
| 100 | "The request included one or more unsupported or misspelled parameters." | Un parámetro es desconocido, está mal escrito o es demasiado largo. La causa suele estar en details. | No: corrige la solicitud. |
Entrega y pago
| Código | Mensaje de Meta | Qué significa | ¿Reintentar? |
|---|---|---|---|
| 131026 | "Unable to deliver message. Reasons can include: The recipient phone number is not a WhatsApp phone number…" | El destinatario no está en WhatsApp, no ha aceptado los términos o usa una versión de la aplicación demasiado antigua. | No: verifica el número y usa otro canal. |
| 131042 | "There was an error related to your payment method." | La cuenta de WhatsApp Business no tiene un método de pago válido en Meta, que factura directamente al cliente. | Una vez que el método de pago se agregue o corrija en Meta. |
| 131047 | "More than 24 hours have passed since the recipient last replied to the sender number." | La ventana de 24 horas de atención al cliente está cerrada: solo puede salir una plantilla aprobada. | No: reenvía el contenido como plantilla. |
| 131049 | "This message was not delivered to maintain healthy ecosystem engagement." | Meta retuvo una plantilla de marketing, casi siempre porque el destinatario alcanzó su límite de marketing. | No antes de 24 horas (los números de EE. UU. son un caso aparte, consulta la página). |
| 131050 | "Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business." | El destinatario dejó de recibir tus mensajes de marketing. | Nunca. |
Plantillas y Flows
| Código | Mensaje de Meta | Qué significa | ¿Reintentar? |
|---|---|---|---|
| 132000 | "The number of variable parameter values included in the request did not match the number of variable parameters defined in the template." | La cantidad de valores enviados no coincide con las variables de la plantilla. | No: envía un valor por variable. |
| 132001 | "The template does not exist in the specified language or the template has not been approved." | No hay ninguna plantilla aprobada con ese nombre en ese idioma. Trampa frecuente: en y en_US son dos plantillas distintas. | No: verifica el nombre, el idioma y el estado. |
| 132015 | "Template is paused due to low quality so it cannot be sent in a template message." | Meta pausó la plantilla por baja calidad. | Cuando se levante la pausa, o con otra plantilla. |
| 132069 | "Flow is in throttled state and 10 messages using this flow were already sent in the last hour." | El Flow está limitado a 10 envíos por hora porque su endpoint no está en buen estado. | Una vez reparado el endpoint. |
¿Dónde encuentro el código de error en Genuka WA?
En dos lugares, según el momento en que Meta rechaza.
Durante la llamada. Cuando Meta rechaza la solicitud, la respuesta de error de Genuka WA trae
un objeto meta: el código de Meta, su clase, retryable, que indica si tiene sentido otro
intento, y traceId, el identificador que pide el soporte de Meta. Ejemplo tomado de la
referencia de la API:
{
"error": "meta_rejected",
"message": "Invalid parameter",
"meta": {
"errorClass": "template",
"retryable": false,
"code": 100,
"details": "body_text example count does not match the number of variables",
"traceId": "AbC…"
}
}Después del envío. Un mensaje aceptado todavía puede fallar en la entrega (131026, 131049,
131050…). El fallo llega entonces a tus webhooks: un evento message_status,
estado failed, con el código de Meta en data.errors:
{
"type": "message_status",
"field": "messages",
"connection_id": "con_1",
"data": {
"id": "wamid.HBgLMjM3...",
"status": "failed",
"recipient_id": "237690000001",
"errors": [{ "code": 131026, "title": "…", "message": "…" }]
}
}Mi código no está en esta lista: ¿dónde busco?
Meta publica la lista completa de códigos de la Cloud API, con la solución que sugiere para cada
uno: códigos de error de la Cloud API.
El campo meta.details contiene el detalle que Meta dio para tu solicitud. Si el rechazo sigue
sin tener sentido, envía al soporte el meta.traceId y el encabezado x-request-id de la
respuesta.
Preguntas frecuentes
¿Qué diferencia hay entre los errores 4, 80007 y 130429?
No limitan lo mismo. El error 4 limita las llamadas de toda la aplicación, 80007 las llamadas de gestión sobre una cuenta de WhatsApp Business (plantillas, números), y 130429 la capacidad de envío de mensajes de un número. Los tres se reintentan más tarde, con esperas crecientes.
¿Debo reintentar automáticamente los errores de WhatsApp?
Solo cuando meta.retryable es true, y con esperas crecientes. Los errores de autorización, de
plantilla y de destinatario fallan igual hasta que se corrige su causa. Un caso especial:
131048 está marcado como reintentable, pero eso significa "más tarde",
no "ahora mismo".
¿Por qué "Application does not have permission for this action" en una plantilla OTP?
Porque la empresa no ha superado la verificación de Meta: sus plantillas de autenticación se rechazan, y el estado de salud de la cuenta muestra el error 141010. El mensaje culpa a la aplicación por error. Consulta también el error 10.
¿El error 131047 significa que mi número está bloqueado?
No. Solo significa que el contacto no te ha escrito en más de 24 horas. Reenvía el contenido como plantilla aprobada; la conversación libre se reanuda en cuanto responda.
Fuentes
Consultadas el 8 de octubre de 2026.
- Meta — Error codes (Cloud API)
- Meta — Health status
Biblioteca TypeScript
@genuka/whatsapp — constructores tipados, validación y normalización de eventos.
Error 0 de WhatsApp: no se pudo autenticar — solución
Error 0 de WhatsApp "We were unable to authenticate the app user": token expirado o invalidado, o acceso cortado. Cómo corregirlo, y el caso de Genuka WA.