Iniciar sesiónEmpezar prueba gratis
Meta Tech Provider

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.

No guardamos mensajes por defectoBusiness App + Cloud APIMCP para Claude y ChatGPTEn vivo en 2 minutos

Petición

CódigoQué significaReintentar
100Un parámetro no es compatible, está mal escrito o mal formado.No
131008No se incluyó en absoluto un parámetro obligatorio.No
131009Un parámetro está presente con un valor que el endpoint rechaza.No
131021El remitente y el destinatario son el mismo número.No
131051El tipo de mensaje no es compatible, a menudo por un límite de Coexistencia.No
131052Meta no pudo descargar un archivo multimedia que envió un cliente.No
131053Meta no pudo subir un archivo multimedia que enviaste. Tamaño, formato o acceso.No

Plantilla

CódigoQué significaReintentar
132000El número de parámetros no coincide con la plantilla.No
132001No existe ninguna plantilla con ese par de nombre e idioma.No
132007La plantilla incumple la política de mensajería. Reescríbela y vuelve a enviarla.No
132012El formato del parámetro no coincide con lo que define la plantilla.No
132015La plantilla está pausada tras una caída de calidad. Es temporal.Espera
132016La plantilla está desactivada de forma permanente. No volverá.No

Ventana y destinatario

CódigoQué significaReintentar
131047La ventana de atención de 24 horas está cerrada. Envía una plantilla.No
131026El destinatario no puede recibir el mensaje en absoluto.No
131050La persona se dio de baja. No hay forma de evitarlo, por diseño.No
130497Enviar mensajes a ese país está restringido para tu cuenta.No

Registro y PIN

CódigoQué significaReintentar
131045El número nunca se registró para enviar mensajes por la Cloud API.No
133010El número no está registrado. Hay que completar el registro.No
133006El número debe verificarse antes de poder registrarse.No
133005El PIN de verificación en dos pasos era incorrecto. Deja de adivinar.No
133008Demasiados intentos de PIN. El registro queda bloqueado durante un tiempo.Espera

Acceso y cuenta

CódigoQué significaReintentar
190El token de acceso caducó o fue invalidado.No
368La cuenta está restringida tras una infracción de políticas.No
131031La cuenta está restringida, o sus datos no coinciden con los de Meta.No
131042Un problema de pago en la cuenta comercial bloquea los envíos.No
131049Meta bloqueó el mensaje para proteger la salud del ecosistema.No

Límites de tasa

CódigoQué significaReintentar
130429Se alcanzó el límite de throughput de mensajes de la cuenta.Espera
131048Se alcanzó un límite de tasa por spam. La causa es la calidad, no el volumen.No
131056Demasiados mensajes entre tu número y un mismo destinatario.No
80007La cuenta alcanzó su límite de llamadas de gestión. Normalmente por polling.Espera

Transitorios

CódigoQué significaReintentar
131016Un servicio de Meta no está disponible temporalmente.Sí
131000Fallo sin clasificar. Reintenta una vez y luego escala con el trace id.Sí

Sincronización de Coexistencia

CódigoQué significaReintentar
2593107Se superó el límite de sincronización del historial de chats.No
2593108Se intentó una sincronización fuera de la ventana de sincronización de 24 horas.No

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.

Sigue leyendo