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.
Request
| Code | What it means | Retry |
|---|---|---|
| 100 | A parameter is unsupported, misspelled or malformed. | No |
| 131008 | A required parameter was not included at all. | No |
| 131009 | A parameter is present with a value the endpoint rejects. | No |
| 131021 | Sender and recipient are the same number. | No |
| 131051 | The message type is not supported, often a Coexistence limit. | No |
| 131052 | Meta could not download media a customer sent. | No |
| 131053 | Meta could not upload media you sent. Size, format or reach. | No |
Template
| Code | What it means | Retry |
|---|---|---|
| 132000 | The number of parameters does not match the template. | No |
| 132001 | No template exists with that name and language pair. | No |
| 132007 | The template breaks messaging policy. Rewrite and resubmit. | No |
| 132012 | Parameter format does not match what the template defines. | No |
| 132015 | The template is paused after a quality decline. Temporary. | Wait |
| 132016 | The template is permanently disabled. It will not come back. | No |
Window and recipient
Registration and PIN
| Code | What it means | Retry |
|---|---|---|
| 131045 | The number was never registered for Cloud API messaging. | No |
| 133010 | The number is not registered. Registration must be completed. | No |
| 133006 | The number must be verified before it can be registered. | No |
| 133005 | The two-step verification PIN was wrong. Stop guessing. | No |
| 133008 | Too many PIN attempts. Registration is locked for a period. | Wait |
Access and account
| Code | What it means | Retry |
|---|---|---|
| 190 | The access token expired or was invalidated. | No |
| 368 | The account is restricted after a policy violation. | No |
| 131031 | The account is restricted, or its data does not match Meta's. | No |
| 131042 | A payment problem on the business account blocks sending. | No |
| 131049 | Meta blocked the message to protect ecosystem health. | No |
Rate limits
Transient
Coexistence sync
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 7 días. Cancela cuando quieras.