# Falhas de envio: pagamento e templates

> Por que um envio falha por forma de pagamento ou por template, e como corrigir.

Cada sintoma abaixo segue o mesmo formato: o que você vê, a causa e o que fazer. Os textos de significado e ação são os mesmos do [catálogo de erros](/errors/).

## Como ler uma falha de envio

Há dois caminhos para uma falha:

- **Na resposta de `POST /v1/messages`.** O erro vem no [formato padrão](/errors/#formato-do-erro): `code`, `meta_code` (o código original da Meta, quando o erro veio dela), `details`, `retryable`, `retry_after_ms` nos erros de limite, `request_id` e `docs_url`. Trate o erro pelo `code`, nunca pelo texto de `message`. Num erro da Meta, `details[0].message` traz o detalhe que ela mandou.
- **Depois, pelo webhook.** A Meta pode aceitar o envio e falhar mais tarde. Nesse caso chega o evento `message.status` com o status `failed`. Veja [Eventos](/webhooks/events/).

Repita só quando `retryable` for `true`. A tabela no fim da página resume cada código.

## Pagamento

**Você vê:** `402` [`meta_payment_required`](/errors#meta_payment_required), com `meta_code` 131042.

**Causa:** a conta do WhatsApp Business está sem forma de pagamento válida, o pagamento falhou ou o limite de crédito acabou. A cobrança das mensagens é da Meta, não do Messajo.

**O que fazer:** ajuste a forma de pagamento no Gerenciador de Negócios da Meta. No painel, o card **Saúde** da conexão mostra o mesmo problema com o código 141006 e a ação **Adicionar forma de pagamento**. Enquanto isso, respostas a clientes que escreveram nas últimas 24 h continuam funcionando; templates, que iniciam conversas, não.

## O template não sai

**Você vê:** `422` [`template_error`](/errors#template_error), com `meta_code` 132000, 132001, 132005, 132007, 132012, 132015, 132016, 132068 ou 132069.

**Causa:** o template não existe nesse idioma, os parâmetros não batem em quantidade ou formato, o texto passou do limite, ou ele está pausado ou desativado.

**O que fazer:** leia `details[].message` e `meta_code`. Confira nome, idioma e parâmetros em **Templates**; um template pausado ou desativado precisa ser editado. Veja [Templates](/guides/templates/).

**Você vê:** `404` [`template_not_found`](/errors#template_not_found).

**Causa:** não há template com esse id, ou com esse nome e idioma, nesta conta do WhatsApp Business.

**O que fazer:** confira nome e idioma, ou sincronize a lista com `POST /v1/templates/sync`.

**Você vê:** `422` [`otp_template_invalid`](/errors#otp_template_invalid).

**Causa:** o template de autenticação citado não existe ou não está `APPROVED`.

**O que fazer:** crie o template em `POST /v1/templates/authentication` e espere a aprovação antes de mandar códigos. Veja [Templates de autenticação](/guides/authentication-templates/).

**Você vê:** o template continua `PENDING` ou aparece como `REJECTED`.

**Causa:** só template aprovado pode ser enviado. O status vem da Meta e chega no evento `template.status`.

**O que fazer:** espere a aprovação, ou edite o template rejeitado e reenvie para revisão. Veja o [ciclo de vida](/guides/templates/#ciclo-de-vida).

**Em campanhas,** dois códigos extras podem aparecer. [`campaign_template_not_approved`](/errors#campaign_template_not_approved): o template não está `APPROVED` ou é de uma categoria que não entra em campanha (só `MARKETING` e `UTILITY`). [`campaign_template_mapping_invalid`](/errors#campaign_template_mapping_invalid): algum parâmetro ficou sem fonte no `variable_mapping`; `details` mostra o `path` de cada um. Veja [Campanhas](/guides/campaigns/).

## O template de marketing não chega

**Você vê:** `422` [`marketing_limit_reached`](/errors#marketing_limit_reached), com `meta_code` 131049.

**Causa:** a Meta segurou o template de marketing para manter o engajamento do contato saudável (limite por usuário).

**O que fazer:** não reenvie em seguida. Espere alguns dias ou mande algo que o contato peça; reenvio imediato não passa.

**Você vê:** `429` [`meta_spam_rate_limited`](/errors#meta_spam_rate_limited), com `meta_code` 131048.

**Causa:** muitas mensagens deste número foram denunciadas ou bloqueadas. Campanhas pausam sozinhas com este erro.

**O que fazer:** não reenvie. Revise a lista (só quem pediu para receber), o conteúdo do template e a frequência, e espere a qualidade do número voltar antes de retomar.

## Fora da janela

**Você vê:** `422` [`outside_service_window`](/errors#outside_service_window), com `meta_code` 131047.

**Causa:** o contato não manda mensagem há mais de 24 h (72 h se veio de anúncio), e só template pode abrir a conversa. O fim da janela vem em `details[0].message`.

**O que fazer:** envie um template aprovado. Quando o contato responder, a janela abre de novo. Veja [Janelas](/api/limits/#janelas).

## Destinatário

**Você vê:** `422` [`recipient_unavailable`](/errors#recipient_unavailable), com `meta_code` 131026.

**Causa:** o número não tem WhatsApp, o app do contato está desatualizado ou ele não aceitou os termos novos.

**O que fazer:** confira o número com DDI. Não repita em seguida: o resultado é o mesmo até o destinatário resolver do lado dele.

**Você vê:** `422` [`recipient_not_allowed`](/errors#recipient_not_allowed), com `meta_code` 131030.

**Causa:** o número de teste da Meta só envia para os destinatários cadastrados no app dela.

**O que fazer:** cadastre o destinatário no painel do app da Meta ou conecte um número de verdade.

## Vazão

**Você vê:** `429` [`connection_rate_limited`](/errors#connection_rate_limited).

**Causa:** o número já envia na velocidade máxima da faixa dele (20 msg/s na coexistência, 80 ou 1000 msg/s só na API). O `typing` também gasta uma vaga.

**O que fazer:** espere `retry_after_ms` e repita. Nada fica na fila: quem repete é a sua integração. Veja [Limites](/api/limits/#envio-por-número).

**Você vê:** `429` [`pair_rate_limited`](/errors#pair_rate_limited), com `meta_code` 131056.

**Causa:** o limite por par (este número e este contato) foi atingido. Outros contatos não são afetados.

**O que fazer:** espere `retry_after_ms` (6 s) antes de mandar de novo para o mesmo contato.

**Você vê:** `429` [`meta_rate_limited`](/errors#meta_rate_limited), com `meta_code` 130429, 80007 ou 4.

**Causa:** a Meta recusou por limite de vazão do número, da conta ou do app, sem processar o pedido.

**O que fazer:** espere `retry_after_ms` (ou o cabeçalho `Retry-After`) e repita.

## Conexão

**Você vê:** `409` com um destes códigos.

| Código | Causa | O que fazer |
|---|---|---|
| [`connection_needs_reconnect`](/errors#connection_needs_reconnect) (`meta_code` 190 ou 102) | O token da Meta foi revogado ou expirou. | Reconecte pelo painel ou pelo link do e-mail que enviamos. Nada sai até reconectar. |
| [`connection_restricted`](/errors#connection_restricted) | A Meta restringiu a conexão. | Veja [Número restrito ou banido](/troubleshooting/number-restricted/). |
| [`connection_disabled`](/errors#connection_disabled) | A Meta desativou a conexão. | Veja [Número restrito ou banido](/troubleshooting/number-restricted/). |
| [`connection_disconnected`](/errors#connection_disconnected) | A conexão foi desconectada. | Conecte de novo pelo painel. |
| [`connection_pending`](/errors#connection_pending) | O cadastro da conexão não terminou. | Conclua a conexão no painel. |
| [`number_not_registered`](/errors#number_not_registered) (`meta_code` 133010) | O registro do número na Cloud API falhou ou foi desfeito. | Abra a conexão e use **Tentar registrar de novo**. Se persistir, reconecte o número. |

## Mídia

**Você vê:** `422` [`media_error`](/errors#media_error) (`meta_code` 131052, 131053 ou 131051), `413` [`media_too_large`](/errors#media_too_large) ou `415` [`media_type_not_supported`](/errors#media_type_not_supported).

**Causa:** a Meta não baixou ou não aceitou a mídia: tipo não suportado, arquivo grande demais ou link inacessível.

**O que fazer:** leia `details[].message`. Confira tipo e tamanho aceitos (imagem 5 MiB, áudio e vídeo 16 MiB, documento 100 MiB) e, se mandou link, que ele é público e responde rápido. Converta para um formato aceito (JPEG ou PNG, MP4, OGG com Opus, PDF) ou mande como documento. Veja [Enviar imagem](/send/image/).

## Resultado desconhecido

**Você vê:** `502` [`meta_unknown_outcome`](/errors#meta_unknown_outcome).

**Causa:** timeout ou falha temporária da Meta num envio. Não dá para saber se a mensagem saiu; ela fica `queued` até o status chegar por webhook.

**O que fazer:** não reenvie às cegas. Confirme pelo `message.status` ou com o contato. Repetir com a mesma `Idempotency-Key` devolve o mesmo 502 sem reenviar; para enviar de novo de propósito, use uma chave nova. O SDK nunca repete esse erro (veja [Repetição segura](/sdk/typescript/#repetição-segura)).

## Repetir ou não

| Código | Status | Repetir? |
|---|---|---|
| `meta_payment_required` | 402 | Não: corrija o pagamento |
| `template_error` | 422 | Não: corrija o template |
| `template_not_found` | 404 | Não: corrija o nome ou sincronize |
| `otp_template_invalid` | 422 | Não |
| `campaign_template_not_approved` | 422 | Não |
| `campaign_template_mapping_invalid` | 422 | Não |
| `marketing_limit_reached` | 422 | Não |
| `meta_spam_rate_limited` | 429 | Não |
| `outside_service_window` | 422 | Não: envie um template |
| `recipient_unavailable` | 422 | Não |
| `recipient_not_allowed` | 422 | Não |
| `connection_rate_limited` | 429 | Sim, depois de `retry_after_ms` |
| `pair_rate_limited` | 429 | Sim, depois de `retry_after_ms` |
| `meta_rate_limited` | 429 | Sim, depois de `retry_after_ms` |
| `connection_needs_reconnect` | 409 | Não: reconecte |
| `connection_restricted`, `connection_disabled`, `connection_disconnected`, `connection_pending` | 409 | Não |
| `number_not_registered` | 409 | Não |
| `media_error` | 422 | Não |
| `media_too_large` | 413 | Não |
| `media_type_not_supported` | 415 | Não |
| `meta_unknown_outcome` | 502 | Não às cegas: confirme pelo `message.status`; a mesma `Idempotency-Key` devolve o mesmo 502, para reenviar use chave nova |

## Falar com o suporte

Mande o `request_id` do erro, que é o mesmo valor do cabeçalho `X-Request-Id`. Com ele o suporte acha a chamada exata, sem que você precise mandar a chave. Veja [X-Request-Id para suporte](/api/authentication/#x-request-id-para-suporte).
