# Códigos de error de WhatsApp

> Qué significa cada código de error de Meta, su causa probable y quién tiene que actuar para resolverlo

Fuente: https://developers.plazbot.com/whatsapp/codigos-de-error/

Cuando un mensaje no se entrega, Meta devuelve un código de error. En el chat lo ves como **Entrega fallida** junto al código (por ejemplo, `Message undeliverable (Código: 131026)`).

Los códigos están agrupados según **quién tiene que actuar** para resolverlo:

> La referencia oficial es la página [Error codes de Meta](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes). Meta agrega códigos nuevos de vez en cuando; si ves uno que no está aquí, búscalo ahí.

---

## Destinatario

Quién actúa: **el contacto**

El mensaje está bien armado, pero el contacto no puede o no quiere recibirlo. Reenviar no sirve.

| Código | Error | Causa probable | Qué hacer |
|---|---|---|---|
| **131026** | No se pudo entregar el mensaje (Message undeliverable · Unable to deliver message.) | El número no tiene WhatsApp, el contacto no aceptó los nuevos Términos de WhatsApp, usa una versión muy antigua de la app o bloqueó al número del negocio. | Confirmar que el número es correcto y tiene WhatsApp. Pedirle (por otro canal) que actualice WhatsApp y acepte los términos en **Ajustes → Ayuda**. |
| **131049** | Límite de engagement de Meta (This message was not delivered to maintain healthy ecosystem engagement.) | Meta no entregó el mensaje de marketing para cuidar la experiencia del usuario: ese contacto ya recibió muchos mensajes de marketing de distintas empresas. | No reenviar enseguida. Esperar al menos 24 horas y priorizar contactos que interactúen. |
| **131050** | El usuario dejó de recibir marketing (Unable to deliver the message.) | El contacto eligió no recibir mensajes de marketing de tu negocio. | **No reintentar.** Respetar la decisión; solo se le puede escribir con plantillas de utilidad o si él inicia la conversación. |
| **131021** | Remitente y destinatario son el mismo (Sender and recipient phone number is the same.) | Se intentó enviar un mensaje al mismo número que lo envía. | Usar otro número de destino. |
| **130403** | Usuario bloqueado por el negocio (Unable to deliver the message.) | El negocio bloqueó a este contacto en WhatsApp. | Desbloquear al usuario si se le quiere volver a escribir. |
| **131052** | No se pudo descargar el archivo del usuario (Unable to download the media sent by the user.) | El archivo que envió el contacto no se pudo descargar (vencido, dañado o no soportado). | Pedirle que lo reenvíe o que lo mande por otro medio (correo, link). |

---

## Agente

Quién actúa: **quien envía el mensaje**

El envío no cumple una regla de WhatsApp. Se resuelve cambiando cómo se envía el mensaje.

| Código | Error | Causa probable | Qué hacer |
|---|---|---|---|
| **131047** | Pasaron más de 24 horas (More than 24 hours have passed since the recipient last replied to the sender number.) | El contacto no escribe desde hace más de 24 horas y la ventana de atención está cerrada. Fuera de la ventana solo se pueden enviar plantillas. | Enviar una **plantilla aprobada**. Cuando el contacto responda, se abre de nuevo la ventana de 24 horas. |
| **131051** | Tipo de mensaje no soportado (Unsupported message type.) | Se envió (o se recibió) un tipo de mensaje que WhatsApp no admite por la API. | Usar texto, imagen, documento, audio, video, ubicación, contacto o plantilla. |
| **131053** | No se pudo subir el archivo (Unable to upload the media used in the message.) | El archivo tiene un formato no soportado, supera el tamaño máximo o el link no es accesible. | Revisar formato y peso. Imágenes JPG/PNG hasta 5 MB, video MP4 hasta 16 MB, documentos hasta 100 MB. |
| **132000** | Cantidad de variables incorrecta (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. | Completar todas las variables de la plantilla antes de enviar. |
| **132012** | Formato de variable incorrecto (Variable parameter values formatted incorrectly.) | Un valor no tiene el formato que espera la plantilla (por ejemplo, una URL, una moneda o una fecha mal formada). | Corregir el valor según el tipo de variable. |
| **131008** | Falta un parámetro obligatorio (The request is missing a required parameter.) | La solicitud no tiene un dato requerido. | Revisar que el mensaje tenga todo lo necesario (texto, archivo, variables). |
| **131009** | Valor de parámetro inválido (One or more parameter values are invalid.) | Algún valor no es válido: número mal escrito, ID de archivo inexistente, botón con datos incorrectos. | Revisar el número del contacto (con código de país) y los datos del mensaje. |
| **100** | Parámetro no soportado (The request included one or more unsupported or misspelled parameters.) | La solicitud tiene un parámetro que no existe o está mal escrito. | Si pasa desde la API, revisar el cuerpo de la solicitud. Si pasa desde la plataforma, reportarlo a soporte. |
| **135000** | Error desconocido en los parámetros (Message failed to send because of an unknown error with your request parameters.) | Meta no pudo interpretar los parámetros. | Revisar el mensaje. Si se repite, reportarlo a soporte con el código. |

---

## Plantillas

Quién actúa: **quien administra las plantillas**

El problema está en la plantilla, no en el contacto. Lo resuelve quien administra las plantillas del workspace.

### Al enviar

| Código | Error | Causa probable | Qué hacer |
|---|---|---|---|
| **132001** | La plantilla no existe o no está aprobada (The template does not exist in the specified language or the template has not been approved.) | El nombre o el idioma no coinciden, la plantilla todavía está en revisión o fue rechazada o eliminada. | Revisar en **Plantillas** que esté aprobada y en el idioma correcto. Sincronizar las plantillas con Meta. |
| **132005** | Traducción demasiado larga (Translated text is too long.) | El texto traducido supera el largo máximo. | Acortar el texto de esa traducción. |
| **132007** | Infringe una política (Template content violates a WhatsApp policy.) | El contenido de la plantilla viola una política de WhatsApp. | Revisar el contenido y crear una plantilla nueva que cumpla las políticas. |
| **132015** | Pausada por baja calidad (Template is paused due to low quality so it cannot be sent in a template message.) | Muchos usuarios la bloquearon o reportaron. | Editar la plantilla para mejorar el contenido o usar otra. |
| **132016** | Deshabilitada permanentemente (Template has been paused too many times due to low quality and is now permanently disabled.) | Se pausó demasiadas veces por baja calidad. | Crear una plantilla nueva con otro contenido. |
| **131063** | Plantillas de marketing deshabilitadas (Your template is categorized as Marketing, but marketing templates are currently disabled for your Cloud API configuration.) | La cuenta tiene deshabilitado el envío de marketing por la Cloud API. | Volver a habilitarlo en Meta o usar la Marketing Messages API. |
| **131064** | Límite por clasificación incorrecta (Message failed to send because this account has reached its messaging limit due to template classification violations.) | Se enviaron plantillas con una categoría que no corresponde a su contenido (por ejemplo, marketing registrada como utilidad). | Revisar la categoría de las plantillas y recategorizar las que correspondan. |
| **132068** | Flow bloqueado (Flow is in blocked state.) | El WhatsApp Flow de la plantilla está bloqueado. | Corregir la configuración del Flow en Meta. |
| **132069** | Flow con límite de envíos (Flow is in throttled state and 10 messages using this flow were already sent in the last hour.) | Se superó el límite de envíos por hora de ese Flow. | Esperar o corregir la configuración del Flow. |
| **2388019** | Límite de plantillas (You have exceeded the maximum number of message templates you can have for this WhatsApp business account.) | La cuenta llegó al máximo de plantillas permitidas. | Eliminar plantillas que ya no se usan. |

### Al crear o editar

| Código | Error | Causa probable | Qué hacer |
|---|---|---|---|
| **2388039** | No se puede cambiar el estado (Message template status can't be changed) | La plantilla está en revisión o ya se alcanzó el límite de ediciones del día. | Esperar a que termine la revisión. Una plantilla aprobada se puede editar pocas veces al día. |
| **2388040** | Se superó el límite de caracteres (A field in your template has exceeded the maximum character limit allowed.) | Un campo tiene más caracteres de los permitidos. | Acortar el texto del campo indicado. |
| **2388047** | Formato de encabezado inválido (Message header format is incorrect) | El encabezado tiene un formato no permitido. | Corregir el encabezado (sin saltos de línea, emojis ni formato no soportado). |
| **2388072** | Formato de cuerpo inválido (Message body format is incorrect) | El cuerpo tiene un formato no permitido. | Revisar el texto y las variables del cuerpo. |
| **2388073** | Formato de pie inválido (Message footer format is incorrect) | El pie tiene un formato no permitido. | Corregir el pie (texto simple, sin variables). |
| **2388293** | Demasiadas variables (Parameters words ratio exceeds limit) | Hay muchas variables para lo corto que es el texto. | Quitar variables o agregar más texto fijo. |
| **2388299** | Variable al inicio o al final (Leading or trailing parameters not allowed) | La plantilla empieza o termina con una variable. | Poner texto fijo antes de la primera variable y después de la última. |

---

## Administrador

Quién actúa: **admin del workspace o de la cuenta de Meta**

El problema está en la configuración del número o de la cuenta de WhatsApp Business. Lo resuelve el admin del workspace o quien administra la cuenta en Meta.

### Conexión y permisos

| Código | Error | Causa probable | Qué hacer |
|---|---|---|---|
| **190** | Token vencido (Your access token has expired.) | La conexión con Meta venció o se revocó. | Reconectar el número de WhatsApp desde **Configuración → Integraciones**. |
| **0** | Falló la autenticación (We were unable to authenticate the app user.) | El token no es válido. | Reconectar el número. |
| **3** · **10** · **200–299** · **131005** | Permiso no otorgado (Capability or permissions issue. / Permission is either not granted or has been removed.) | Falta un permiso o se revocó al conectar la cuenta. | Reconectar el número aceptando todos los permisos. |
| **33** | Número eliminado (The business phone number has been deleted.) | El número de WhatsApp se eliminó de la cuenta de Meta. | Revisar el número en Meta y volver a conectarlo. |
| **131045** | Error de registro del número (Message failed to send due to a phone number registration error.) | El número no está registrado correctamente en la plataforma. | Volver a registrar el número. |
| **133010** | Número no registrado (Phone number not registered on the WhatsApp Business Platform.) | El número no está registrado en WhatsApp Business Platform. | Registrar el número. |
| **131037** | Sin nombre visible aprobado (The 555 business phone number used to send the request does not have an approved display name.) | El número no tiene el nombre visible (display name) aprobado. | Pedir la aprobación del nombre visible en WhatsApp Manager. |

### Cuenta, pago y calidad

| Código | Error | Causa probable | Qué hacer |
|---|---|---|---|
| **131042** | Problema con el método de pago (There was an error related to your payment method.) | La cuenta no tiene método de pago válido, la tarjeta falló o se agotó la línea de crédito. | Revisar la facturación en **Meta Business Suite → Facturación**. |
| **368** | Cuenta restringida (The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy.) | La cuenta de WhatsApp Business fue restringida o deshabilitada por infringir políticas. | Revisar el aviso en WhatsApp Manager y apelar si corresponde. |
| **131031** | Cuenta bloqueada o datos que no coinciden (The WhatsApp Business Account associated with the app has been restricted or disabled for violating a platform policy, or we were unable to verify data included in the request against data set on the WhatsApp Business Account.) | Infracción de políticas o falla en la verificación de la cuenta. | Revisar el estado de la cuenta en WhatsApp Manager. |
| **130497** | País restringido (The WhatsApp Business Account is restricted from messaging to users in certain countries.) | La cuenta no puede enviar mensajes a ese país. | Revisar qué países están permitidos para la categoría del negocio. |
| **131048** | Calidad del número restringida (Message failed to send because there are restrictions on how many messages can be sent from this phone number.) | Muchos mensajes anteriores fueron bloqueados o reportados como spam. | Revisar la calidad del número en WhatsApp Manager y bajar el volumen de envíos masivos. |
| **134011** | Términos de Pagos pendientes (Message failed to send because WhatsApp Payments terms of service acceptance is pending for this WhatsApp Business Account.) | Falta aceptar los términos de WhatsApp Payments. | Aceptar los términos en Meta. |

### Registro y migración del número

| Código | Error | Causa probable | Qué hacer |
|---|---|---|---|
| **2388012** | El número ya existe (This phone number already exists in your list of phone numbers.) | El número ya está en la cuenta. | Usar otro número o revisar dónde está registrado. |
| **2388091** · **2388093** | No elegible para verificación (This phone number isn't eligible to receive/verify a registration code since it is not being migrated.) | El número no está en proceso de migración. | Registrar y verificar el número directamente. |
| **2388103** | Falló la migración (Cannot migrate phone number.) | Hay distintos impedimentos para migrar el número. | Revisar el detalle del error en Meta. |
| **133000** | Falló la baja anterior (A previous deregistration attempt failed.) | Un intento anterior de dar de baja el número falló. | Darlo de baja de nuevo y volver a registrarlo. |
| **133005** | PIN de verificación incorrecto (Two-step verification PIN incorrect.) | El PIN de verificación en dos pasos no es correcto. | Revisar el PIN o restablecerlo en WhatsApp Manager. |
| **133006** | Número no verificado (Phone number needs to be verified before registering.) | El número debe verificarse antes de registrarlo. | Verificar el número y volver a registrarlo. |
| **133008** · **133009** | Demasiados intentos de PIN (Too many two-step verification PIN guesses for this phone number. / Two-step verification PIN was entered too quickly.) | Se probó el PIN demasiadas veces o demasiado rápido. | Esperar el tiempo indicado y volver a intentarlo. |
| **133015** | Número eliminado hace poco (The phone number you are attempting to register was recently deleted, and deletion has not yet completed.) | El número se eliminó hace pocos minutos. | Esperar 5 minutos y reintentar. |
| **133016** | Intentos de registro bloqueados (Registration or Deregistration failed because there were too many attempts for this phone number in a short period of time) | Hubo demasiados intentos de registro para el número. | Esperar a que expire el bloqueo. |
| **2593107** · **2593108** | Error de sincronización (coexistencia) (You have exceeded the maximum number of times to call the synchronization api for this phone number. / Synchronization request can only be made within 24 hours of onboarding) | Se superó el límite de sincronizaciones con la app de WhatsApp Business, o pasaron más de 24 horas desde la conexión. | Desconectar y volver a conectar el número. |

---

## Temporal

Quién actúa: **nadie, solo reintentar**

Fallas de Meta o límites de velocidad. No hay nada que corregir: hay que esperar y reintentar.

| Código | Error | Causa probable | Qué hacer |
|---|---|---|---|
| **130429** | Límite de velocidad de envío (Cloud API message throughput has been reached.) | Se superó la cantidad de mensajes por segundo del número. | Reintentar en unos segundos. En campañas, bajar la velocidad de envío. |
| **131056** | Demasiados mensajes al mismo contacto (Too many messages sent from the sender phone number to the same recipient phone number in a short period of time.) | Se enviaron muchos mensajes al mismo contacto en poco tiempo. | Esperar antes de volver a escribirle a ese contacto. |
| **4** · **80007** | Límite de llamadas a la API (The app has reached its API call rate limit. / The WhatsApp Business Account has reached its rate limit.) | La app o la cuenta llegó a su límite de solicitudes. | Esperar y reintentar. Si es frecuente, reportarlo a soporte. |
| **131000** | Error desconocido (Message failed to send due to an unknown error.) | Meta no pudo enviar el mensaje por un motivo no especificado. | Reintentar. Si se repite, reportarlo a soporte con el código. |
| **1** · **2** | Error de Meta o servicio no disponible (Invalid request or possible server error. / Temporary due to downtime or due to being overloaded.) | Falla del servidor de Meta o servicio caído o saturado. | Revisar el [estado de la plataforma](https://metastatus.com/whatsapp-business-api) y reintentar. |
| **131016** · **133004** | Servicio no disponible temporalmente (A service is temporarily unavailable. / Server is temporarily unavailable.) | Un servicio de Meta no está disponible. | Reintentar más tarde. |
| **131057** · **2494100** | Cuenta en mantenimiento (Business Account is in maintenance mode / The business phone number is in maintenance mode.) | El número o la cuenta están en modo de mantenimiento. | Reintentar en unos minutos. |
| **130472** | Excluido por un experimento (Message was not sent as part of an experiment.) | Meta no envió el mensaje porque el contacto forma parte de un experimento de marketing. | Nada; es un comportamiento de Meta. |

---

## Errores de la Marketing Messages API

Quién actúa: **quien envía marketing por MM Lite**

> **Marketing Messages:** Solo aplican si la cuenta envía marketing por la **Marketing Messages API** (MM Lite).

| Código | Error | Causa probable | Qué hacer |
|---|---|---|---|
| **131055** · **134100** | Solo plantillas de marketing (Only marketing template messages are supported / Only marketing messages supported) | Esta API solo acepta plantillas de categoría marketing. | Enviar una plantilla de categoría **Marketing**. |
| **134101** | Plantilla sincronizándose (Your template is still syncing) | La plantilla todavía se está sincronizando (puede tardar hasta 10 minutos). | Esperar 10 minutos y reintentar. |
| **134102** | Plantilla no disponible (Template unavailable for use) | La cuenta no cumple los requisitos para esta API. | Revisar la elegibilidad de la cuenta. |
| **132018** | Error en los parámetros de la plantilla (There's an issue with the parameters in your template.) | Hay un problema con las variables de la plantilla. | Corregir las variables y reenviar. |
| **1752041** | Solicitud duplicada (Duplicate Request is thrown when a client has already been invited to onboard by any partner.) | La cuenta ya fue invitada. | Nada; la cuenta se incorpora automáticamente. |