> ## Documentation Index > Fetch the complete documentation index at: https://docs.ararahq.com/llms.txt > Use this file to discover all available pages before exploring further. # Erros de envio > Por que uma mensagem aceita pela API terminou em FAILED: códigos, causa e o que fazer. 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](/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. ```bash theme={null} curl https://api.ararahq.com/v1/messages/ara_msg_k9Bf2Xq \ -H "Authorization: Bearer $ARARA_API_KEY" ``` 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`](/webhooks/events). | Código | O que aconteceu | O que fazer | | - | - | - | | `ararahq-63016` | Janela de 24h fechada (rota legada Twilio). | Envie um template aprovado. | | `ararahq-reengagement` | Passaram mais de 24h desde a última mensagem do cliente (Meta `131047`). | Envie um template aprovado. Veja [Janela de 24h](/concepts/24h-window). | | `ararahq-63032` | O aparelho não recebeu a mensagem. | Não reenvie em seguida. Tente outro dia ou outro canal. | | `ararahq-invalid-number` | Número inválido ou sem WhatsApp. | Corrija o número ou remova o contato. | | `ararahq-invalid-recipient` | Destinatário inválido ou indisponível. | Remova o contato da lista. | | `ararahq-meta-block` | Bloqueio de spam ou limite de marketing por usuário da Meta. | Pare a campanha para essa lista e revise o conteúdo. | | `ararahq-opt-out` | O destinatário bloqueou o seu número. | Remova o contato. Não reenvie. | | `ararahq-undeliverable` | A Meta não entregou. | Não reenvie. Limpe a lista. | | `ararahq-display-name` | O nome de exibição do número não está aprovado. | Peça a aprovação do nome no Business Manager. | | `ararahq-account-locked` | A conta WhatsApp Business está bloqueada. | Conteste no Business Manager e abra um chamado. | | `ararahq-user-experiment` | O destinatário está em um experimento da Meta que limita marketing. | Nada a fazer. Não reenvie. | | `ararahq-template-mismatch` | As variáveis não batem com o template. | Compare `templateVariables` com o template aprovado. | | `ararahq-template-not-found` | O template não existe ou não está aprovado. | Confira o nome e o status em Templates. | | `ararahq-insufficient-funds` | Saldo insuficiente. | Recarregue a carteira. | | `ararahq-rate-limit` | Limite de envio atingido. | Reduza o ritmo e envie de novo. | | `ararahq-media-invalid` | A mídia não pôde ser usada. | Confira a URL, o formato e o tamanho do arquivo. | | `ararahq-canceled` | O envio foi cancelado. | Nada a fazer. | | `ararahq-` | Falha do provedor sem tradução própria (ex.: `ararahq-63041`). | Leia o texto de `reason`. Se repetir em volume, abra um chamado. | 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](/concepts/24h-window). *** ## 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: | Regra | Detalhe | | - | - | | Variáveis sequenciais | `{{1}}`, `{{2}}`, `{{3}}`. Pular de `{{1}}` para `{{3}}` reprova. | | Nunca no começo nem no fim | O corpo não pode abrir nem fechar com variável. | | Nunca coladas | `{{1}} {{2}}` reprova. Precisa de texto entre elas. | | Variável no cabeçalho conta na sequência | Cabeçalho com `{{1}}` faz o corpo começar em `{{2}}`. É o erro mais comum de quem monta na mão. | | Sem caracteres especiais na variável | `#`, `$`, `%` dentro do valor reprovam. | | Espaçamento | Mais de 4 espaços seguidos, tabs ou várias linhas em branco reprovam. | | Emoji | Mais de 10 no corpo reprova. | | Tamanho | Corpo acima de 550 caracteres reprova. | | Duplicado | Template com corpo ou rodapé igual a outro já aprovado na conta reprova, exceto na categoria `AUTHENTICATION`. | Categoria errada também reprova: promoção enviada como `UTILITY` é reclassificada ou recusada. Veja [Templates](/concepts/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. | Erro | O que significa | | - | - | | **A Meta não conseguiu entregar** (`ararahq-undeliverable`, Meta `131026`) | O número pode não ter WhatsApp, ter recusado o recebimento ou não aceitar mensagens da sua empresa. | | **A Meta limitou o envio para este usuário** (`ararahq-meta-block`, Meta `131048` e `131049`) | Limite de marketing por usuário ou sinal de spam. A Meta segurou para preservar a experiência da pessoa. | | **Experimento da Meta** (`ararahq-user-experiment`, Meta `130472`) | O usuário está num teste da Meta que limita marketing. Nada a fazer. | | **Destinatário inválido ou indisponível** (`ararahq-invalid-recipient`) | Número sem WhatsApp ativo, com termos pendentes ou app incompatível. | | **Mensagem não pôde ser entregue no aparelho** (`ararahq-63032`, números legados) | Telefone desligado, sem sinal ou com você bloqueado. | 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. | Tier | Teto diário aplicado pela Arara | | - | - | | `TIER_50` | 50 | | `TIER_250` | 250 | | `TIER_1K` | 1.000 | | `TIER_2K` | 1.000 (a Meta informa 2.000) | | `TIER_10K` | 10.000 | | `TIER_100K` | 100.000 | | `UNLIMITED` | Sem limite | | `UNKNOWN` | 1.000 (tier ainda não sincronizado) | Para subir de tier é preciso volume consistente com qualidade alta. Envio agressivo derruba a qualidade e trava a subida. Veja [Números](/numbers). *** ## 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.