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.
Como ler uma falha de envio
Seção intitulada “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:code,meta_code(o código original da Meta, quando o erro veio dela),details,retryable,retry_after_msnos erros de limite,request_idedocs_url. Trate o erro pelocode, nunca pelo texto demessage. Num erro da Meta,details[0].messagetraz o detalhe que ela mandou. - Depois, pelo webhook. A Meta pode aceitar o envio e falhar mais tarde. Nesse caso chega o evento
message.statuscom o statusfailed. Veja Eventos.
Repita só quando retryable for true. A tabela no fim da página resume cada código.
Pagamento
Seção intitulada “Pagamento”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.
O template não sai
Seção intitulada “O template não sai”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.
O template de marketing não chega
Seção intitulada “O template de marketing não chega”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.
Fora da janela
Seção intitulada “Fora da janela”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.
Destinatário
Seção intitulada “Destinatário”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.
Conexão
Seção intitulada “Conexão”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.
Resultado desconhecido
Seção intitulada “Resultado desconhecido”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).
Repetir ou não
Seção intitulada “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
Seção intitulada “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.