Quando dá erro

Antes de procurar o código, descubra de onde ele veio. São duas tabelas nesta página, e olhar na errada é meia hora perdida. E existe um terceiro caso, o pior de todos, em que nada dá erro e nada chega: ele tem seção própria aqui embaixo.

De onde veio o erro

São três origens, e cada uma tem um formato diferente. Reconhecer o formato já resolve metade.

Mandei e não chegou

É o caso mais comum de chegar até aqui, e quase sempre ele não é erro nenhum. Percorra nesta ordem, e pare no primeiro que responder não.

1. A chamada voltou 200 com um wamid? Se não voltou, o erro está no corpo da resposta, e o código dele está na tabela da Meta. Vá para ela.
2. Voltou. Então a Meta aceitou, e o problema não está na sua chamada. "message_status": "accepted" quer dizer aceita, nunca entregue.
3. A janela de 24 horas está aberta? Texto livre só chega para quem escreveu para o seu número nas últimas 24 horas. Fora dela, o caminho é modelo aprovado. Detalhe em A janela de 24 horas e em Modelos de mensagem.
4. O destino está em E.164 sem o sinal de mais? Um celular de São Paulo fica 5511987654321. Sem espaço, sem parêntese e sem traço.
5. Você está esperando a resposta da pessoa, e não a sua ida? Então leia O erro que não dá erro antes de continuar depurando. É o caso em que o seu código está certo e a entrega nunca foi apontada para você.

O formato do erro da Meta

A Meta devolve o erro dentro do corpo, e não só no status. Estes são os campos que o produto da Zera lê de verdade quando trata uma falha da Graph.

{
  "error": {
    "message": "...",
    "type": "OAuthException",
    "code": 190,
    "error_subcode": ...,
    "error_data": { "details": "..." },
    "fbtrace_id": "..."
  }
}

• Decida pelo code, nunca pelo message. É regra escrita no nosso executor, e ela veio da própria documentação da Meta, que avisa para não construir lógica em cima do texto. Um if que procura palavra dentro da frase quebra no dia em que a Meta reescrever a frase, e quebra em silêncio.
• A mesma frase junta causas diferentes. A Graph responde does not exist, cannot be loaded due to missing permissions, or does not support this operation para três situações distintas. Quem lê a frase acerta o caso inofensivo e engole o perigoso.
• error_data.details é onde mora o tempo de espera. Quando a Meta manda esperar, ela diz quanto ali dentro, em texto livre. Não crave um número no seu código: leia o que veio.
• error_subcode aparece só em parte dos erros, e ele afina o code. O valor está com reticências acima de propósito: cravar um número ali seria um exemplo que ninguém mediu. Um subcódigo que a Zera mediu é o 33, que vem junto do code 100 quando o identificador do caminho não existe.
• fbtrace_id é o que o suporte da Meta pede. Guarde no seu registro, junto com o horário.

Os erros da Meta

Estes são os códigos que a Zera trata no próprio código ou mediu em chamada real. Cada linha diz onde a Zera viu.

Os outros que o produto classifica sem traduzir

O executor da Zera separa mais alguns códigos em duas caixas, para decidir se tenta de novo. Ele não traduz cada um, e esta página também não vai inventar a frase de nenhum deles. O que dá para dizer com honestidade é a caixa em que cada um caiu.

• Tratados como passageiros: 1, 17, 341, 80008, 131000, 133004 e 133015. Tentar de novo daqui a pouco tem chance.
• Tratados como definitivos: 131031, 133005, 133006 e 133010. Insistir não destrava e ainda gasta chamada.
• Código que não está em nenhuma das listas também é tratado como definitivo, e isso é escolha, não descuido. Insistir num erro que ninguém entende, num endereço que cria conta de verdade na Meta, é como se descobre um limite depois de queimar todas as tentativas dele.

Se você bater num código que não está nesta página, a autoridade é a referência de erros da Meta. E escreva para a Zera: a sua medição vira uma linha nova aqui.

As recusas do painel

Estas são as respostas das rotas /api/... do painel. Elas não são uma API pública da Zera: não existe chave da Zera, não existe endereço da Zera no caminho do seu envio, e o que você faz com a credencial vai direto para a Meta. Elas aparecem quando o painel recusa alguma coisa na sua frente, e a chave é sempre a mesma palavra.

{ "ok": false, "erro": "sessao_velha" }

Algumas respostas trazem um campo a mais, e ele é útil: teto_por_dia diz qual é o limite que você encostou, proxima_em diz a partir de quando dá para tentar de novo, e lido_em diz de quando é o valor que continua na tela.

proxima_em e lido_em vêm em segundos desde 1970, e não em milissegundos. Em JavaScript, comparar com Date.now() direto dá uma espera de dezenas de milhares de anos, ou de zero, e não levanta erro nenhum. Compare com Math.floor(Date.now() / 1000).

O erro que não dá erro

1. O webhook apontado no nível da conta, que some na reconexão

Esta seção mudou em 23 de setembro de 2026. Até 22 de setembro ela dizia que o campo de webhook do painel guardava o endereço e não configurava nada na Meta. Isso era verdade e deixou de ser: desde 23 de setembro, com a escrita ligada em produção, o salvamento aponta a sobreposição no seu número. O código que faz isso existe desde 15 de setembro, e até o dia 22 ficou desligado. O caso que sobra é outro, e continua sendo um erro que não dá erro.

A Meta aceita sobreposição de endereço em três níveis: número, conta de WhatsApp e aplicativo. Apontar no nível da conta funciona, a releitura confirma, as mensagens começam a chegar, e um dia elas param.

Por quê: toda vez que o seu número é reconectado, por autorização revogada ou por troca de número, a Zera assina o aplicativo dela na sua conta com POST /{waba_id}/subscribed_apps sem corpo. A própria Meta documenta que assinar sem parâmetros apaga a sobreposição da conta. A sobreposição do número não é tocada por isso, e tem precedência sobre a da conta.

O sintoma: tudo funcionou por semanas, o número foi reconectado num dia qualquer, e a partir dali o seu servidor parou de receber. Nada dá erro, nenhuma configuração sua mudou, e o painel não tem como saber de uma sobreposição que ele não escreveu.

O que fazer: aponte pelo painel, em Canais, no número, aba Detalhes, cartão Ajustes de API. Ele escreve no nível do número e relê para confirmar. O passo a passo, e o caminho manual para quando o painel devolver erro, estão em Receber mensagens. Aquela página também diz, com todas as letras, que nenhum número percorreu isso de ponta a ponta em produção até hoje.

2. O escopo que ninguém confere

A conexão do número confere que o seu token carrega whatsapp_business_management, que é o escopo de gerenciar a conta. Se ele não carregar esse escopo com conta nenhuma, a conexão falha ali mesmo, com mensagem clara.

O escopo que faz POST /{phone_number_id}/messages funcionar é outro: whatsapp_business_messaging. Ele não é conferido em lugar nenhum do produto. A busca por esse nome nas pastas de código, functions/ e public/js/, devolve zero ocorrências: ele só aparece em páginas desta documentação. E é para você poder conferir por conta própria, não para você acreditar na nossa palavra.

Quais escopos a janela de conexão pede é configuração do Embedded Signup, guardada na Meta atrás do identificador de configuração, e ela vive fora deste repositório. Então esta página não afirma que o seu token tem o escopo de envio, nem que ele é pedido: ela afirma a única coisa que dá para conferir aqui, que é que nada verifica.

O sintoma: a conexão termina bem, o painel mostra o número, a leitura de estado na Meta funciona, e o primeiro envio volta erro 200. Como as leituras usam o escopo de gerenciamento, tudo o que você olha na tela parece saudável.

O que fazer: reconecte o número e autorize tudo o que a Meta pedir na janela. Se o 200 voltar no envio depois disso, escreva para a Zera antes de reescrever o seu código: o problema não está nele.

3. Aceita não é entregue

A resposta de um envio bem-sucedido traz "message_status": "accepted" e um wamid. Aceita quer dizer que a Meta recebeu a sua mensagem e assumiu a entrega. Não quer dizer que ela chegou no aparelho de alguém.

Entrega e leitura existem em um lugar só: no corpo do webhook, dentro de statuses[], com o mesmo wamid que voltou no envio. Ou seja, enquanto o seu servidor não estiver recebendo os eventos daquele número, você não tem como saber se alguma mensagem sua chegou.

O que fazer agora: guarde o wamid de todo envio, mesmo antes de o recebimento estar de pé. Sem ele, quando os eventos começarem a chegar, entrega e leitura chegam sem dono e não dá para ligar nenhuma delas ao que você mandou.

Quando nada disso resolve

Escreva para [email protected]. Um chamado com estas cinco coisas costuma ser respondido na primeira resposta; sem elas, a primeira resposta é um pedido de informação.

• A resposta crua da Graph, o objeto error inteiro, com code, error_subcode, error_data.details, fbtrace_id e message. Copie como veio, sem resumir: o fbtrace_id é o que o suporte da Meta pede.
• O wamid, quando houve envio. É por ele que nós encontramos a mensagem do lado da Meta.
• O horário, com o fuso. Sem fuso, três horas de diferença viram três horas de procura no lugar errado.
• O método e o caminho exatos que você chamou, incluindo a versão. Sem o token, e sem o cabeçalho Authorization.
• O telefone e o phone_number_id do número envolvido.