Solución de problemas
Fallos de envío: pago y plantillas
Por qué un envío falla por el método de pago o por una plantilla, y cómo corregirlo.
Cada síntoma de abajo sigue el mismo formato: lo que ves, la causa y qué hacer. Los textos de significado y acción son los mismos del catálogo de errores.
Cómo leer un fallo de envío
Sección titulada «Cómo leer un fallo de envío»Un fallo llega por dos caminos:
- En la respuesta de
POST /v1/messages. El error viene en el formato estándar:code,meta_code(el código original de Meta, cuando el error vino de ella),details,retryable,retry_after_msen los errores de límite,request_idydocs_url. Trata el error por elcode, nunca por el texto demessage. En un error de Meta,details[0].messagetrae el detalle que ella envió. - Después, por el webhook. Meta puede aceptar el envío y fallar más tarde. En ese caso llega el evento
message.statuscon el estadofailed. Consulta Eventos.
Reintenta solo cuando retryable sea true. La tabla al final de la página resume cada código.
Ves: 402 meta_payment_required, con meta_code 131042.
Causa: la cuenta de WhatsApp Business no tiene un método de pago válido, el pago falló o se agotó el límite de crédito. El cobro de los mensajes es de Meta, no de Messajo.
Qué hacer: ajusta el método de pago en el Administrador de Negocios de Meta. En el panel, la tarjeta Salud de la conexión muestra el mismo problema con el código 141006 y la acción Agregar método de pago. Mientras tanto, las respuestas a clientes que escribieron en las últimas 24 h siguen funcionando; las plantillas, que inician conversaciones, no.
La plantilla no sale
Sección titulada «La plantilla no sale»Ves: 422 template_error, con meta_code 132000, 132001, 132005, 132007, 132012, 132015, 132016, 132068 o 132069.
Causa: la plantilla no existe en ese idioma, los parámetros no coinciden en cantidad o formato, el texto pasó del límite, o está pausada o desactivada.
Qué hacer: lee details[].message y meta_code. Revisa nombre, idioma y parámetros en Plantillas; una plantilla pausada o desactivada hay que editarla. Consulta Plantillas.
Ves: 404 template_not_found.
Causa: no hay plantilla con ese id, o con ese nombre e idioma, en esta cuenta de WhatsApp Business.
Qué hacer: revisa nombre e idioma, o sincroniza la lista con POST /v1/templates/sync.
Ves: 422 otp_template_invalid.
Causa: la plantilla de autenticación citada no existe o no está APPROVED.
Qué hacer: crea la plantilla con POST /v1/templates/authentication y espera la aprobación antes de enviar códigos. Consulta Plantillas de autenticación.
Ves: la plantilla sigue PENDING o aparece como REJECTED.
Causa: solo una plantilla aprobada se puede enviar. El estado viene de Meta y llega en el evento template.status.
Qué hacer: espera la aprobación, o edita la plantilla rechazada y envíala de nuevo a revisión. Consulta el ciclo de vida.
En campañas pueden aparecer dos códigos más. campaign_template_not_approved: la plantilla no está APPROVED o es de una categoría que no entra en campañas (solo MARKETING y UTILITY). campaign_template_mapping_invalid: algún parámetro quedó sin fuente en variable_mapping; details muestra el path de cada uno. Consulta Campañas.
La plantilla de marketing no llega
Sección titulada «La plantilla de marketing no llega»Ves: 422 marketing_limit_reached, con meta_code 131049.
Causa: Meta retuvo la plantilla de marketing para mantener sano el engagement del contacto (límite por usuario).
Qué hacer: no reenvíes enseguida. Espera unos días o envía algo que el contacto pida; un reenvío inmediato no pasa.
Ves: 429 meta_spam_rate_limited, con meta_code 131048.
Causa: se denunciaron o bloquearon muchos mensajes de este número. Las campañas se pausan solas con este error.
Qué hacer: no reenvíes. Revisa la lista (solo quien pidió recibir), el contenido de la plantilla y la frecuencia, y espera a que la calidad del número se recupere antes de retomar.
Fuera de la ventana
Sección titulada «Fuera de la ventana»Ves: 422 outside_service_window, con meta_code 131047.
Causa: el contacto no escribe hace más de 24 h (72 h si vino de un anuncio), y solo una plantilla puede abrir la conversación. El fin de la ventana viene en details[0].message.
Qué hacer: envía una plantilla aprobada. Cuando el contacto responda, la ventana se abre de nuevo. Consulta Ventanas.
Destinatario
Sección titulada «Destinatario»Ves: 422 recipient_unavailable, con meta_code 131026.
Causa: el número no tiene WhatsApp, la app del contacto está desactualizada o no aceptó los términos nuevos.
Qué hacer: revisa el número con su prefijo de país. No repitas enseguida: el resultado es el mismo hasta que el destinatario lo resuelva de su lado.
Ves: 422 recipient_not_allowed, con meta_code 131030.
Causa: el número de prueba de Meta solo envía a los destinatarios registrados en su app.
Qué hacer: registra al destinatario en el panel de la app de Meta o conecta un número real.
Ves: 429 connection_rate_limited.
Causa: el número ya envía a la velocidad máxima de su franja (20 msg/s en coexistencia, 80 o 1000 msg/s solo con API). El typing también gasta un cupo.
Qué hacer: espera retry_after_ms y reintenta. Nada queda en cola: el reintento lo hace tu integración. Consulta Límites.
Ves: 429 pair_rate_limited, con meta_code 131056.
Causa: se alcanzó el límite por par (este número y este contacto). Los demás contactos no se ven afectados.
Qué hacer: espera retry_after_ms (6 s) antes de volver a escribirle al mismo contacto.
Ves: 429 meta_rate_limited, con meta_code 130429, 80007 o 4.
Causa: Meta rechazó por límite de caudal del número, de la cuenta o de la app, sin procesar la solicitud.
Qué hacer: espera retry_after_ms (o el encabezado Retry-After) y reintenta.
Conexión
Sección titulada «Conexión»Ves: 409 con uno de estos códigos.
| Código | Causa | Qué hacer |
|---|---|---|
connection_needs_reconnect (meta_code 190 o 102) |
El token de Meta fue revocado o venció. | Reconecta desde el panel o desde el enlace del correo que enviamos. Nada sale hasta reconectar. |
connection_restricted |
Meta restringió la conexión. | Consulta Número restringido o baneado. |
connection_disabled |
Meta desactivó la conexión. | Consulta Número restringido o baneado. |
connection_disconnected |
La conexión fue desconectada. | Conéctala de nuevo desde el panel. |
connection_pending |
El alta de la conexión no terminó. | Completa la conexión en el panel. |
number_not_registered (meta_code 133010) |
El registro del número en la Cloud API falló o se deshizo. | Abre la conexión y usa Reintentar registro. Si persiste, reconecta el número. |
Multimedia
Sección titulada «Multimedia»Ves: 422 media_error (meta_code 131052, 131053 o 131051), 413 media_too_large o 415 media_type_not_supported.
Causa: Meta no descargó o no aceptó el archivo: tipo no admitido, archivo demasiado grande o enlace inaccesible.
Qué hacer: lee details[].message. Revisa el tipo y el tamaño aceptados (imagen 5 MiB, audio y video 16 MiB, documento 100 MiB) y, si enviaste un enlace, que sea público y responda rápido. Convierte a un formato aceptado (JPEG o PNG, MP4, OGG con Opus, PDF) o envíalo como documento. Consulta Enviar imagen.
Resultado desconocido
Sección titulada «Resultado desconocido»Ves: 502 meta_unknown_outcome.
Causa: timeout o fallo temporal de Meta en un envío. No hay forma de saber si el mensaje salió; queda queued hasta que el estado llegue por webhook.
Qué hacer: no reenvíes a ciegas. Confirma con message.status o con el contacto. Repetir con la misma Idempotency-Key devuelve el mismo 502 sin reenviar; para enviar de nuevo a propósito, usa una clave nueva. El SDK nunca repite este error (consulta Reintentos seguros).
Reintentar o no
Sección titulada «Reintentar o no»| Código | Estado | ¿Reintentar? |
|---|---|---|
meta_payment_required |
402 | No: corrige el pago |
template_error |
422 | No: corrige la plantilla |
template_not_found |
404 | No: corrige el nombre o sincroniza |
otp_template_invalid |
422 | No |
campaign_template_not_approved |
422 | No |
campaign_template_mapping_invalid |
422 | No |
marketing_limit_reached |
422 | No |
meta_spam_rate_limited |
429 | No |
outside_service_window |
422 | No: envía una plantilla |
recipient_unavailable |
422 | No |
recipient_not_allowed |
422 | No |
connection_rate_limited |
429 | Sí, después de retry_after_ms |
pair_rate_limited |
429 | Sí, después de retry_after_ms |
meta_rate_limited |
429 | Sí, después de retry_after_ms |
connection_needs_reconnect |
409 | No: reconecta |
connection_restricted, connection_disabled, connection_disconnected, connection_pending |
409 | No |
number_not_registered |
409 | No |
media_error |
422 | No |
media_too_large |
413 | No |
media_type_not_supported |
415 | No |
meta_unknown_outcome |
502 | No a ciegas: confirma con message.status; la misma Idempotency-Key devuelve el mismo 502, para reenviar usa una clave nueva |
Hablar con soporte
Sección titulada «Hablar con soporte»Envía el request_id del error, que es el mismo valor del encabezado X-Request-Id. Con él, soporte encuentra la llamada exacta sin que tengas que enviar tu clave. Consulta X-Request-Id para soporte.