KewbotEn resumen
Los errores de la WhatsApp Cloud API llegan como un número y un mensaje corto que rara vez explica la causa real. La mayoría cae en cinco familias: pago y elegibilidad, política y entrega, restricción de cuenta, registro y número, y plantillas y contenido. Abajo están los más frecuentes, cada uno con qué significa y cómo se arregla. Buscá el número que te apareció en el índice y saltá directo.
El problema está en el método de pago o la facturación
131042 Business eligibility payment issue
"There is an issue with payment method / business eligibility"
Es de los más comunes y casi siempre significa lo mismo: hay un problema con el método de pago de la cuenta de WhatsApp Business. Tarjeta vencida, rechazada, sin fondos, o una línea de crédito de Meta no configurada. Si administrás cuentas de clientes, este es el que aparece cuando la tarjeta del cliente falla y le frena todos los envíos.
Cómo se arreglaEntrá a la configuración de facturación de WhatsApp en el Business Manager de la cuenta afectada y revisá el método de pago: que la tarjeta esté vigente, verificada y con fondos. En cuentas de clientes, confirmá que la responsabilidad de pago esté bien asignada. Una vez corregido el pago, los envíos se reactivan solos.
141006 Payment issue on the WABA
"There is an error with the payment configuration"
Variante del anterior, orientada a la configuración de pago de la propia WABA. El chequeo de salud (health_status) marca can_send_message: BLOCKED. La causa raíz es la misma familia: la cuenta no puede facturar, así que no puede enviar.
Cómo se arreglaRevisá que la WABA tenga un método de pago válido y asociado correctamente en el Business Manager. Si migraste de proveedor hace poco, verificá que la línea de crédito o la tarjeta hayan quedado bien vinculadas a la cuenta nueva.
Meta decidió no entregar el mensaje
131049 Healthy ecosystem engagement
"This message was not delivered to maintain healthy ecosystem engagement"
El error más reportado de todos. No es un fallo técnico: Meta eligió deliberadamente no entregar ese mensaje. Suele estar atado al límite por usuario de plantillas de marketing: si a esa persona ya le llegaron muchas plantillas de marketing en poco tiempo, Meta corta para no saturarla. También aparece cuando el usuario tiene baja probabilidad de interactuar con marketing.
Cómo se arreglaNo lo reintentes al toque: reenviar de inmediato solo repite el error. Esperá al menos 24 horas antes de volver a enviar esa plantilla a ese usuario. En el fondo, la solución es de estrategia: mandá menos marketing y más relevante, segmentá mejor, y priorizá plantillas utility (que no chocan con este límite) cuando el mensaje sea transaccional y no promocional.
131026 Message undeliverable
"Message undeliverable"
Un "no se pudo entregar" amplio. Las causas típicas: el número no está en WhatsApp o no es alcanzable, el destinatario nunca aceptó recibir mensajes de tu empresa, o la cuenta no cumple algún requisito de elegibilidad para ese envío. A veces también aparece por incompatibilidad de categoría de plantilla.
Cómo se arreglaVerificá que el número exista en WhatsApp y esté bien formateado (código de país incluido, sin el "+" según el endpoint). Confirmá que tengas opt-in de ese contacto. Si es masivo y falla solo en algunos, limpiá la lista de números inválidos en lugar de reintentar en bloque.
La cuenta está restringida o bloqueada
130497 Restricted from messaging in this country
"Business account is restricted from messaging users in this country"
Tu WABA está restringida para enviar a usuarios de cierto país. Las cuentas nuevas solo pueden mensajear a los países para los que fueron habilitadas; enviar a un país no autorizado dispara este error. Es muy común al empezar y querer mandar a un número de afuera.
Cómo se arreglaEl envío entre países se desbloquea al completar una ruta de escalado y alcanzar el tier de 2.000 mensajes. Puede tardar hasta 30 días en habilitarse después de lograrlo. Ojo: para algunos destinos (por ejemplo Brasil e Indonesia) puede no habilitarse aunque cumplas el escalado. Mientras tanto, enviá solo a los países aprobados.
131031 Business account locked / restricted
"Business account locked"
La cuenta fue restringida o bloqueada, normalmente por violaciones de política o discrepancias en la verificación: spam, contenido que rompe las reglas, o algo que activó la revisión de integridad de Meta. Junto con el 130497 y el 368, forma la familia de restricciones por integridad/política.
Cómo se arreglaRevisá el estado de la cuenta en el Business Manager y en la Calidad de la cuenta de WhatsApp. Si hay una violación marcada, corregí la causa (bajá el ritmo de envíos, ajustá el contenido a política) y presentá la apelación desde el propio panel. No sirve reintentar el envío: primero hay que levantar la restricción.
Problemas con el número, el registro o el nombre
131037 Display name approval required
"The number used does not have an approved display name"
El número desde el que enviás no tiene un nombre para mostrar aprobado, o el que cargaste todavía está pendiente de aprobación. Hasta que el display name no esté aprobado, no podés enviar.
Cómo se arreglaConfigurá el nombre para mostrar y esperá la aprobación de Meta. Asegurate de que cumpla las guías de nombre (que coincida con tu marca, sin promociones ni caracteres raros). Si trabajás con un BSP, el nombre lo gestiona él.
133005 / 133006 / 133010 Registro del número
"Wrong PIN / re-verification needed / number not registered"
La familia 133xxx tiene que ver con el registro del número en la Cloud API. 133005: PIN de verificación en dos pasos incorrecto. 133006: el número necesita re-verificarse. 133010: el número no está registrado en la API.
Cómo se arreglaPara 133005, ingresá el PIN correcto de verificación en dos pasos; si no lo tenés (típico al migrar de un proveedor caído), primero hay que desactivar la verificación en dos pasos desde el WhatsApp Manager del dueño de la WABA. Para 133006 y 133010, volvé a correr el registro del número en la API. Estos son exactamente los errores que aparecen al portar un número entre proveedores.
Ritmo de envío, formato y flujos
131048 / 130429 Límite de ritmo (spam / rate limit)
"Spam rate limit hit / Rate limit hit"
Estás enviando más rápido de lo permitido. 130429 es el límite de tasa general; 131048 es el límite de tasa por spam (Meta detectó un patrón de envío que parece abuso). Aparecen en campañas grandes mal escalonadas.
Cómo se arreglaBajá la cadencia de envío y aplicá reintentos con backoff exponencial (esperas cada vez más largas), no reintentos inmediatos. Escaloná las campañas grandes en el tiempo. Si es 131048, además revisá calidad y opt-in: el patrón que disparó el "spam" suele venir de listas frías o envíos demasiado agresivos.
131053 Media upload error
"Media upload error"
Falló la subida o descarga del archivo multimedia (imagen, PDF, audio). Causa frecuente: la URL del archivo redirige (301), pide sesión, o el servidor de medios de Meta no la pudo bajar. En los logs a veces se ve junto a errores HTTP 500/502 al bajar el archivo desde el weblink.
Cómo se arreglaEvitá URLs que redirijan o que dependan de cookies de sesión: el fetcher de Meta no las sigue bien. Serví el archivo desde una URL pública y directa (un objeto público en un bucket, sin URLs firmadas ni con vencimiento). Verificá también el tamaño y el formato permitido por WhatsApp.
132018 Parámetro de plantilla inválido
"Parameter format mismatch / invalid parameter"
El contenido que pasás a una variable de plantilla no cumple el formato esperado. Clásico: mandar saltos de línea (\n), tabs o ciertos caracteres dentro de una variable, cuando la plantilla no los admite en ese punto.
Limpiá el valor de la variable: sacá saltos de línea y caracteres de control, respetá el formato (posicional vs. nombrado) con el que se creó la plantilla, y no metas en una variable contenido que debería ir en el cuerpo fijo. Si necesitás una lista larga, reformulala para que entre en el formato permitido.
139000 Blocked by integrity
"Blocked by Integrity" (a veces con subcódigo)
Meta bloqueó una acción (por ejemplo publicar un flujo) por su chequeo de integridad. Suele aparecer con flujos (Flows) o al operar en modo desarrollo con permisos incompletos.
Cómo se arreglaVerificá que la app y la cuenta tengan la verificación de negocio y los permisos completos, y que no estés en una limitación de modo desarrollo. Si el subcódigo apunta a una limitación de Dev Mode, completá primero la revisión y aprobación de la app. Revisá también que el contenido del flujo no viole política.
⚠️ Lo que siempre conviene guardar antes de escalar
Cuando un error te supere y tengas que escalar a soporte, guardá siempre estos datos: el código y mensaje completos, el error_data.details, el fbtrace_id, el wamid (si Meta aceptó el envío), el ID del número y de la WABA, y si era plantilla, su nombre e idioma. Con eso el soporte resuelve en una vuelta; sin eso, te piden todo y perdés días. No mandes el contenido del mensaje salvo que te lo pidan explícitamente.
Preguntas frecuentes
¿Por qué el mensaje del error no explica la causa real?
Porque Meta usa mensajes genéricos por diseño. El mismo código puede tener varias causas concretas, y el texto corto rara vez las distingue. Por eso conviene mirar el error_data.details y el fbtrace_id, que dan más pistas que el título.
Recibí un error y reintenté igual. ¿Está mal?
Depende del error. Los de límite (131049, 130429, 131048) empeoran si reintentás de inmediato: hay que esperar y usar backoff. Los de pago, restricción o registro no se resuelven reintentando: primero hay que corregir la causa (pago, apelación, re-registro).
¿Hay una lista oficial y completa de todos los códigos?
Sí, Meta publica la referencia completa en su documentación de la Cloud API, y va cambiando (agregan códigos nuevos, como el 131064). Esta guía cubre los que más aparecen en la práctica, no los cientos que existen. Para uno raro, la referencia oficial es la fuente.
Muchos errores míos son de pago o restricción. ¿Qué hago?
Si se repiten, suele ser una señal de que la cuenta necesita orden: método de pago bien configurado, calidad y opt-in sanos, y escalado de límites hecho como corresponde. Resolver la raíz una vez evita que vuelvan en cadena.
¿Trabado con un error que no cede?
Onboardeamos y operamos cuentas en WhatsApp Business API, con acceso a soporte directo de Meta para escalar los casos que lo necesitan. Si estás peleando con un error, escribinos y lo miramos.
Ir a Kewbot →