Skip to main content
Esta página cobre a mensagem que a API aceitou (202) e que falhou depois, com status FAILED. Se a chamada foi recusada na hora (4xx/5xx), veja Erros. O erro diz de quem é o problema: template, conta, destinatário ou provedor. Descubra isso primeiro.

​
Onde ver o motivo

Cada mensagem guarda o motivo da falha.
Quando a mensagem está FAILED, o campo reason traz o motivo traduzido. O webhook message.status_updated traz o mesmo motivo em data.errorDetails. No painel, Logs mostra o mesmo, com filtro por status. O formato do motivo depende do provedor do número:
  • Números no provedor atual (Meta via Gupshup): texto corrido com o que aconteceu e o que fazer, sem código. Ex.: “O nome de exibição do seu número ainda não foi aprovado pela Meta. … Peça a aprovação do nome de exibição…”
  • Números legados (Twilio): JSON em string com code (ararahq-...), whatHappened e howToAct.
O valor de uma mensagem que falhou depois do aceite é estornado na carteira.

​
Códigos ararahq

Todo motivo de falha reconhecido tem um código ararahq-*. Onde ele aparece depende do provedor do número:
  • Recusa na hora por falha do provedor: em error.code, com error.details.diagnostic.
  • Números legados (Twilio): em reason e em data.errorDetails.code do webhook.
  • Números no provedor atual: reason e data.errorDetails trazem só o texto, sem código. Não dependa do código nesse caso. Veja message.status_updated.
As seções abaixo detalham os casos mais comuns.

​
Erros de template

São a maior parte das falhas. Quase sempre o problema está no template, não no envio.

​
Falha na validação do template: 401 UNAUTHORIZED

O que é: a Arara não conseguiu se autenticar para validar seu template no provedor. Apesar do texto falar em “estrutura e links”, 401 é credencial, não conteúdo. Não adianta mexer no texto do template. O que fazer: não é ação sua. Abra um chamado: é a conta do número que precisa ser reconectada do nosso lado. Se você acabou de trocar o número ou refazer o embedded signup, mencione isso no chamado.

​
Template rejeitado, pausado ou inexistente

Aparece como “O template usado não existe ou não está aprovado nesta conta WhatsApp” (ararahq-template-not-found). Se o template já estava pausado antes do envio, a API recusa na hora com 422 TEMPLATE_PAUSED. O que é: a Meta reprovou ou pausou um template que já estava aprovado. Pausa acontece quando muita gente bloqueia ou denuncia mensagens daquele template. O que fazer:
  1. Veja o status em Templates. Pausado aparece como PAUSED.
  2. Template pausado volta sozinho depois de um período, mas volta a pausar se o conteúdo continuar gerando bloqueio.
  3. A correção real é o conteúdo: mensagem que a pessoa não esperava receber gera bloqueio. Revise a lista e o texto antes de resubmeter.

​
Falha na validação das variáveis: Content Variables inválido

Também aparece como “As variáveis enviadas não batem com a estrutura do template aprovado” (ararahq-template-mismatch). Quando a Arara detecta a diferença antes de enviar, a API responde 422 TEMPLATE_VARIABLES_MISMATCH com details.expected e details.received. O que é: a quantidade ou o formato das variáveis que você mandou não corresponde ao template aprovado. Template com {{1}} e {{2}} exige exatamente dois valores, na ordem. O que fazer: compare templateVariables com o corpo aprovado em Templates. Erros comuns: mandar um valor a mais, pular posição, mandar null ou string vazia.

​
Falha na validação do template: 413 PAYLOAD_TOO_LARGE

O que é: o conteúdo passou do tamanho aceito, normalmente uma variável muito longa, ou mídia grande demais no cabeçalho. O que fazer: encurte o valor da variável. Para mídia, use link em vez de anexo pesado.

​
Janela de 24h fechada

A API recusa na hora com 422 CONVERSATION_WINDOW_CLOSED. Se a janela fechou entre o aceite e o envio, a falha chega como “Passaram-se mais de 24h desde a última mensagem do cliente” (ararahq-reengagement). O que é: você tentou mandar texto livre, botões ou lista para quem não falou com você nas últimas 24h. O que fazer: fora da janela, só template aprovado passa. Informe templateName. Veja Janela de 24h.

​
Por que a Meta reprova um template

Reprovação por formato costuma vir como INVALID_FORMAT, e quase sempre é variável fora de posição. As regras duras: Categoria errada também reprova: promoção enviada como UTILITY é reclassificada ou recusada. Veja Templates.

​
Erros de conta e número

Aqui nada que você mude no envio resolve. É o estado da conta na Meta.

​
A conta WhatsApp (WABA) da sua empresa está bloqueada ou restrita

Código ararahq-account-locked (erro Meta 131031). O que é: a Meta bloqueou a conta inteira. Nenhum envio sai enquanto durar. O que fazer: o aviso e o motivo chegam no Business Manager da sua empresa. É lá que se abre a contestação. A Arara não consegue destravar por você, mas o chamado ajuda a interpretar o motivo e montar o recurso.

​
Bloqueio preventivo de Spam pela Meta

Código interno ararahq-meta-block. O que é: o conteúdo foi classificado como marketing excessivo, ou houve denúncia de usuários. O que fazer: pare o envio para aquela lista. Continuar enviando enquanto o bloqueio está ativo piora a nota de qualidade e aproxima a restrição definitiva.

​
O nome de exibição do seu número ainda não foi aprovado

Código ararahq-display-name (erro Meta 131037). O que é: sem nome aprovado, a Meta bloqueia envio de template. O que fazer: peça a aprovação do nome no Business Manager. Enquanto isso, conversa dentro da janela de 24h continua funcionando.

​
Erros do destinatário

Não são erro seu nem nosso. Não adianta reenviar. Número que falha repetidamente passa a ser recusado antes do envio com 403 NUMBER_BLOCKED. Reenviar para esses contatos não melhora a entrega e piora sua nota de qualidade. O certo é limpar a lista.

​
Erros de provedor

​
Erro de entrega no provedor (Upstream Error)

Códigos ararahq-63041 e similares. O que é: a Arara enviou, o provedor aceitou, mas a confirmação não voltou. Um dos motivos que aparece é low balance do lado do provedor. O que fazer: normalmente resolve sozinho e a mensagem é reconciliada. Se um lote inteiro ficar assim, abra chamado. É sinal de incidente, não de conteúdo.

​
Mensagem parada em SENT_TO_PROVIDER

Na API e no webhook esse estado aparece como SENT / sent; o nome técnico só aparece no histórico do painel. O que é: aceita pelo provedor e sem status final. Não é falha: é ausência de confirmação. O que fazer: aguarde a reconciliação. Se persistir por horas em volume, abra chamado citando o período.

​
Limite de envio e qualidade do número

Duas coisas diferentes que costumam ser confundidas:
  • Qualidade é a saúde do número (verde, amarelo, vermelho). Cai quando gente bloqueia ou denuncia.
  • Tier é quantas conversas você pode iniciar por dia.
Para subir de tier é preciso volume consistente com qualidade alta. Envio agressivo derruba a qualidade e trava a subida. Veja Números.

​
Como o retry funciona

Falha de rede e erro temporário do provedor entram em retry automático com backoff. Erro de template, de variável e de conta não entram: repetir daria o mesmo resultado e pioraria a qualidade do número. Se a mensagem está FAILED, ela não será reenviada sozinha. Corrija a causa e envie de novo.

​
Ainda travado?

Abra um chamado em Suporte, dentro do painel. O assistente responde na hora com base nesta documentação; o que ele não resolver vai para a fila do time com o prazo do seu plano. Ajuda muito no chamado: o id da mensagem (ara_msg_...), o nome do template, o texto de reason e o horário aproximado.