# 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](/es/errors/).

## 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](/es/errors/#formato-del-error): `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](/es/webhooks/events/).

Reintenta solo cuando `retryable` sea `true`. La tabla al final de la página resume cada código.

## Pago

**Ves:** `402` [`meta_payment_required`](/es/errors#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

**Ves:** `422` [`template_error`](/es/errors#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](/es/guides/templates/).

**Ves:** `404` [`template_not_found`](/es/errors#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`](/es/errors#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](/es/guides/authentication-templates/).

**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](/es/guides/templates/#ciclo-de-vida).

**En campañas** pueden aparecer dos códigos más. [`campaign_template_not_approved`](/es/errors#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`](/es/errors#campaign_template_mapping_invalid): algún parámetro quedó sin fuente en `variable_mapping`; `details` muestra el `path` de cada uno. Consulta [Campañas](/es/guides/campaigns/).

## La plantilla de marketing no llega

**Ves:** `422` [`marketing_limit_reached`](/es/errors#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`](/es/errors#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

**Ves:** `422` [`outside_service_window`](/es/errors#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](/es/api/limits/#ventanas).

## Destinatario

**Ves:** `422` [`recipient_unavailable`](/es/errors#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`](/es/errors#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.

## Caudal

**Ves:** `429` [`connection_rate_limited`](/es/errors#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](/es/api/limits/#envío-por-número).

**Ves:** `429` [`pair_rate_limited`](/es/errors#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`](/es/errors#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

**Ves:** `409` con uno de estos códigos.

| Código | Causa | Qué hacer |
|---|---|---|
| [`connection_needs_reconnect`](/es/errors#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`](/es/errors#connection_restricted) | Meta restringió la conexión. | Consulta [Número restringido o baneado](/es/troubleshooting/number-restricted/). |
| [`connection_disabled`](/es/errors#connection_disabled) | Meta desactivó la conexión. | Consulta [Número restringido o baneado](/es/troubleshooting/number-restricted/). |
| [`connection_disconnected`](/es/errors#connection_disconnected) | La conexión fue desconectada. | Conéctala de nuevo desde el panel. |
| [`connection_pending`](/es/errors#connection_pending) | El alta de la conexión no terminó. | Completa la conexión en el panel. |
| [`number_not_registered`](/es/errors#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

**Ves:** `422` [`media_error`](/es/errors#media_error) (`meta_code` 131052, 131053 o 131051), `413` [`media_too_large`](/es/errors#media_too_large) o `415` [`media_type_not_supported`](/es/errors#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](/es/send/image/).

## Resultado desconocido

**Ves:** `502` [`meta_unknown_outcome`](/es/errors#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](/es/sdk/typescript/#reintentos-seguros)).

## 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

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](/es/api/authentication/#x-request-id-para-soporte).
