Códigos de error de la WhatsApp Cloud API
Esta es la lista de todos los códigos de error de la WhatsApp Cloud API que documentamos, en una sola tabla, con lo que significa cada uno y si reintentarlo ayuda. La mayoría no ayuda: son deterministas, así que la misma petición falla igual y un bucle de reintentos convierte una petición mala en un límite de tasa.
EasyCoexistence monitorea la conexión de forma continua y registra los eventos de cuenta y de calidad de Meta en la línea de tiempo de la conexión, así los errores que vienen del estado de un número quedan visibles antes de que un envío falle y no después.
Petición
| Código | Qué significa | Reintentar |
|---|---|---|
| 100 | Un parámetro no es compatible, está mal escrito o mal formado. | No |
| 131008 | No se incluyó en absoluto un parámetro obligatorio. | No |
| 131009 | Un parámetro está presente con un valor que el endpoint rechaza. | No |
| 131021 | El remitente y el destinatario son el mismo número. | No |
| 131051 | El tipo de mensaje no es compatible, a menudo por un límite de Coexistencia. | No |
| 131052 | Meta no pudo descargar un archivo multimedia que envió un cliente. | No |
| 131053 | Meta no pudo subir un archivo multimedia que enviaste. Tamaño, formato o acceso. | No |
Plantilla
| Código | Qué significa | Reintentar |
|---|---|---|
| 132000 | El número de parámetros no coincide con la plantilla. | No |
| 132001 | No existe ninguna plantilla con ese par de nombre e idioma. | No |
| 132007 | La plantilla incumple la política de mensajería. Reescríbela y vuelve a enviarla. | No |
| 132012 | El formato del parámetro no coincide con lo que define la plantilla. | No |
| 132015 | La plantilla está pausada tras una caída de calidad. Es temporal. | Espera |
| 132016 | La plantilla está desactivada de forma permanente. No volverá. | No |
Ventana y destinatario
| Código | Qué significa | Reintentar |
|---|---|---|
| 131047 | La ventana de atención de 24 horas está cerrada. Envía una plantilla. | No |
| 131026 | El destinatario no puede recibir el mensaje en absoluto. | No |
| 131050 | La persona se dio de baja. No hay forma de evitarlo, por diseño. | No |
| 130497 | Enviar mensajes a ese país está restringido para tu cuenta. | No |
Registro y PIN
| Código | Qué significa | Reintentar |
|---|---|---|
| 131045 | El número nunca se registró para enviar mensajes por la Cloud API. | No |
| 133010 | El número no está registrado. Hay que completar el registro. | No |
| 133006 | El número debe verificarse antes de poder registrarse. | No |
| 133005 | El PIN de verificación en dos pasos era incorrecto. Deja de adivinar. | No |
| 133008 | Demasiados intentos de PIN. El registro queda bloqueado durante un tiempo. | Espera |
Acceso y cuenta
| Código | Qué significa | Reintentar |
|---|---|---|
| 190 | El token de acceso caducó o fue invalidado. | No |
| 368 | La cuenta está restringida tras una infracción de políticas. | No |
| 131031 | La cuenta está restringida, o sus datos no coinciden con los de Meta. | No |
| 131042 | Un problema de pago en la cuenta comercial bloquea los envíos. | No |
| 131049 | Meta bloqueó el mensaje para proteger la salud del ecosistema. | No |
Límites de tasa
| Código | Qué significa | Reintentar |
|---|---|---|
| 130429 | Se alcanzó el límite de throughput de mensajes de la cuenta. | Espera |
| 131048 | Se alcanzó un límite de tasa por spam. La causa es la calidad, no el volumen. | No |
| 131056 | Demasiados mensajes entre tu número y un mismo destinatario. | No |
| 80007 | La cuenta alcanzó su límite de llamadas de gestión. Normalmente por polling. | Espera |
Transitorios
Sincronización de Coexistencia
Cómo leer la columna de reintento
Tiene tres valores, y elegir mal entre ellos es el error más caro de toda esta referencia.
No significa que el fallo es determinista. La petición, la plantilla o el estado del destinatario es lo que falló, y enviar la petición idéntica otra vez produce el error idéntico mientras consume throughput que vas a querer después. Sí significa que el fallo estuvo del lado de Meta y que un backoff lo resuelve de verdad. Espera significa que la condición es real pero temporal: un límite o un bloqueo que se levanta solo, donde reintentar antes de que se levante no hace nada y puede prolongarlo.
Por qué la mayoría no es reintentable
Porque la plataforma devuelve códigos específicos en vez de genéricos. Un parámetro malformado, una plantilla que no existe, una ventana de mensajería cerrada y un destinatario que se dio de baja son todos conocibles en el momento de la respuesta, así que Meta los nombra en lugar de fallar de forma vaga.
- Un problema de petición no se vuelve correcto en el segundo intento.
- Un problema de plantilla vive en la plantilla, que la petición no puede cambiar.
- Un problema de ventana o de baja es sobre el estado del destinatario, no sobre el tuyo.
- Una restricción de cuenta es una decisión, y reintentar no es una apelación.
Qué registrar cuando llega uno de estos
Lo suficiente para diagnosticarlo sin reproducirlo, que es la diferencia entre un arreglo de cinco minutos y un día de adivinanzas.
- La respuesta de error completa, incluido el trace id, que es lo que pide el soporte de Meta.
- El cuerpo de la petición tal como se envió, no como se pretendía. La distancia entre esos dos suele ser el bug.
- El phone number id, para que un problema en un número se distinga de uno en toda la cuenta.
- La marca de tiempo, para que el fallo pueda contrastarse con el estado de la conexión en ese momento.
Los códigos que solo existen en la Coexistencia
Son dos, y confunden a la gente porque parecen fallos comunes de envío. El 2593107 y el 2593108 se refieren los dos a la sincronización del historial de conversaciones, que es el paso que copia las conversaciones recientes de la app de WhatsApp Business cuando un número se conecta por primera vez.
No son errores de mensajería y no significan que la conexión falló. Una sincronización que excede su límite o que corre fuera de su ventana deja el número conectado y enviando con normalidad, con menos historial copiado del esperado. Leerlos como una conexión rota lleva a la gente a desconectar y empezar otra vez, lo que pierde más historial en vez de recuperarlo.
Preguntas frecuentes
¿Qué errores debo reintentar?
El 131016 y el 131000, con backoff exponencial. El 130429, el 132015 y el 133008 se resuelven solos si esperas. Todo lo demás es determinista.
¿Un código de error significa que mi número está desconectado?
Por lo general no. La mayoría se refiere a la petición, a la plantilla o al destinatario. Los problemas de conexión aparecen como webhooks de cuenta y de calidad, no como errores de envío.
¿Qué es un trace id?
Un identificador en la respuesta de error que permite al soporte de Meta encontrar esa petición concreta. Regístralo en cada fallo; sin él un ticket no puede atenderse.
¿Estos códigos son iguales en todos los proveedores?
Sí. Vienen de la Cloud API de Meta, así que son idénticos sea cual sea el proveedor que conectó el número. Un proveedor solo puede cambiar con qué claridad te llegan.
¿Listo para empezar?
Configura WhatsApp Coexistence en minutos, no en meses. La app sigue funcionando en el teléfono.
Empezar prueba gratisNo se cobra nada durante 3 días. Cancela cuando quieras.