Pular para o conteúdo

Solução de problemas

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.

Há dois caminhos para uma falha:

  • Na resposta de POST /v1/messages. O erro vem no formato padrão: 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.

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

Você vê: 402 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.

Você vê: 422 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.

Você vê: 404 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.

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.

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.

Em campanhas, dois códigos extras podem aparecer. 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: algum parâmetro ficou sem fonte no variable_mapping; details mostra o path de cada um. Veja Campanhas.

Você vê: 422 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, 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.

Você vê: 422 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.

Você vê: 422 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, 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.

Você vê: 429 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.

Você vê: 429 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, 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.

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

Código Causa O que fazer
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 A Meta restringiu a conexão. Veja Número restrito ou banido.
connection_disabled A Meta desativou a conexão. Veja Número restrito ou banido.
connection_disconnected A conexão foi desconectada. Conecte de novo pelo painel.
connection_pending O cadastro da conexão não terminou. Conclua a conexão no painel.
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.

Você vê: 422 media_error (meta_code 131052, 131053 ou 131051), 413 media_too_large ou 415 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.

Você vê: 502 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).

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

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.