Ir al contenido

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.

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_ms en los errores de límite, request_id y docs_url. Trata el error por el code, nunca por el texto de message. En un error de Meta, details[0].message trae 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.status con el estado failed. 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.

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.

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.

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.

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.

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.

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.

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).

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

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.