Atualizado em 25/10/2026
O erro 131047 da API do WhatsApp significa que já se passaram mais de 24 horas desde a última mensagem do cliente, então a janela de atendimento fechou e texto livre não é mais aceito. A solução é enviar um template aprovado. Os outros códigos comuns seguem a mesma lógica: cada um aponta uma causa (destinatário, limite, template, conta ou token) e uma ação, e a Meta recomenda tratar o erro pelo code, não pelo status HTTP.
Este guia reúne os códigos que mais aparecem em produção, todos conferidos na tabela oficial de códigos de erro da Meta, e mostra como separar o que pode ser reenviado do que não deve ser.
Onde os erros aparecem
A Cloud API devolve erros em dois lugares, e às vezes nos dois:
- Na resposta síncrona da chamada de envio, quando o problema é detectado na hora: token inválido, parâmetro errado, template inexistente, limite de chamadas.
- No webhook
messages, de forma assíncrona, quando a mensagem foi aceita mas não pôde ser entregue. Nesse caso chega um statusfailedcom o arrayerrors.
Por isso não basta olhar o 200 OK do envio. Uma mensagem aceita pela API pode falhar minutos depois. O artigo sobre status de mensagem via webhook mostra como guardar esses eventos.
Formato do erro síncrono
{
"error": {
"message": "(#130429) Rate limit hit",
"type": "OAuthException",
"code": 130429,
"error_data": {
"messaging_product": "whatsapp",
"details": "Cloud API message throughput has been reached."
},
"fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
}
}Os campos que importam:
code: o número que você usa na lógica. A Meta orienta construir o tratamento em cima dele.error_data.details: a explicação mais específica, às vezes com a correção sugerida. Grave sempre no log.fbtrace_id: identificador para abrir chamado no suporte da Meta.error_subcode: marcado como descontinuado; não aparece a partir da versão 16.0 da API.
Formato do erro no webhook
Quando a falha é na entrega, o evento de status traz o mesmo code. Este é o exemplo da documentação oficial, com o erro 131049:
{
"statuses": [
{
"id": "wamid.HBgLNTU4NDk5OTk5OTk5...",
"status": "failed",
"timestamp": "1761400000",
"recipient_id": "5584999999999",
"errors": [
{
"code": 131049,
"title": "This message was not delivered to maintain healthy ecosystem engagement.",
"message": "This message was not delivered to maintain healthy ecosystem engagement.",
"error_data": {
"details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
},
"href": "/documentation/business-messaging/whatsapp/support/error-codes"
}
]
}
]
}Erros que não estão ligados a uma mensagem específica podem chegar em entry.changes.value.errors. A estrutura geral dos eventos está no guia de webhooks da API do WhatsApp.
Os códigos mais comuns e o que fazer
| Código | O que significa | O que fazer |
|---|---|---|
| 131047 | Mais de 24 horas desde a última resposta do cliente | Enviar um template aprovado |
| 131026 | Mensagem não entregue: o destinatário não usa WhatsApp, não aceitou os termos atuais ou usa versão antiga do app | Confirmar o número por outro canal; não reenviar em loop |
| 131049 | Mensagem de marketing não entregue para manter o engajamento saudável (limite por usuário) | Esperar pelo menos 24 horas antes de reenviar |
| 131050 | O destinatário parou de receber mensagens de marketing da empresa | Não reenviar; marcar opt-out |
| 131056 | Muitas mensagens do mesmo número para o mesmo destinatário em pouco tempo | Esperar e tentar de novo para esse destinatário |
| 130429 | Limite de taxa de envio (throughput) da Cloud API atingido | Reduzir o ritmo e reenviar com espera crescente |
| 131048 | Envio restrito porque mensagens anteriores foram bloqueadas ou marcadas como spam | Verificar a qualidade no WhatsApp Manager |
| 130472 | Mensagem não enviada por fazer parte de um experimento de mensagens de marketing | Ver a documentação do experimento; não é falha do seu código |
| 131042 | Problema na forma de pagamento | Revisar a conta de pagamento, limite de crédito, moeda e fuso |
| 131051 | Tipo de mensagem não suportado | Usar um tipo aceito pela API |
| 131053 | Falha ao subir a mídia usada na mensagem | Conferir o tipo MIME e o formato do arquivo |
| 131000 | Erro desconhecido | Tentar de novo; se persistir, abrir chamado |
| 131016 | Serviço temporariamente indisponível | Ver a página de status da plataforma e reenviar |
131047: janela de 24 horas fechada
Ele aparece sempre que alguém tenta mandar texto livre, imagem ou botão para um contato que não falou com a empresa nas últimas 24 horas. A janela de atendimento abre a cada mensagem do cliente. Fora dela, só template.
A correção tem duas partes. No código, antes de enviar, verifique quando chegou a última mensagem daquele wa_id e escolha template se passou de 24 horas. No produto, use um template de utilidade ou marketing para retomar a conversa: quando o cliente responder, a janela abre de novo. As regras completas estão em janela de 24 horas do WhatsApp.
131026: mensagem não entregue
A Meta lista três causas: o número não tem WhatsApp, a pessoa não aceitou os termos ou a política de privacidade mais recentes, ou usa uma versão antiga do aplicativo. A API não diz qual das três aconteceu. Reenviar a mesma mensagem não resolve. Marque o contato, peça confirmação por outro canal (e-mail, SMS) e revise a origem da sua base: um número digitado errado cai no primeiro caso.
131049 e 131050: limites de marketing
O 131049 é o limite por usuário de templates de marketing: a Meta segura a mensagem para não saturar quem já recebe muito marketing. A orientação oficial é esperar pelo menos 24 horas antes de tentar de novo. Reenviar na mesma hora só gera outra falha. O tema tem artigo próprio: limite de marketing por usuário.
O 131050 é diferente: a pessoa escolheu parar de receber marketing da sua empresa. Não reenvie. Trate como opt-out e, se quiser acompanhar essas mudanças, assine o webhook user_preferences.
131056 e 130429: ritmo de envio
O 131056 é um limite por par de números: muitas mensagens do seu número para o mesmo destinatário em pouco tempo. Os outros destinatários não são afetados, então só aquela fila precisa esperar.
O 130429 é o limite de throughput do número. Distribua o envio no tempo e reenvie com espera exponencial. Para campanhas, veja limite de mensagens.
Erros de template (132xxx)
| Código | O que significa | O que fazer |
|---|---|---|
| 132000 | Número de variáveis enviado diferente do definido no template | Mandar um valor para cada variável |
| 132001 | Template não existe no idioma pedido ou não está aprovado | Conferir nome, código de idioma (ex.: pt_BR) e status |
| 132005 | Texto traduzido longo demais | Encurtar a tradução no WhatsApp Manager |
| 132007 | Conteúdo do template viola uma política do WhatsApp | Revisar o texto e submeter de novo |
| 132012 | Formato dos valores das variáveis não bate com o template | Ajustar ao formato definido (ex.: mídia no cabeçalho) |
| 132015 | Template pausado por qualidade baixa | Editar o template e aguardar nova aprovação |
| 132016 | Template pausado vezes demais e desativado de forma permanente | Criar outro template com conteúdo diferente |
| 132068 | Flow em estado bloqueado | Corrigir o Flow |
| 132069 | Flow limitado: já foram enviadas 10 mensagens com ele na última hora | Corrigir o Flow |
O 132001 costuma ser erro de digitação: pt_br em vez de pt_BR, nome com maiúscula ou template ainda em análise. O 132000 aparece quando alguém edita o template e esquece de atualizar o código que monta os parameters. Os templates são detalhados em templates da API do WhatsApp, e os Flows em WhatsApp Flows.
Erros de token, permissão e conta
| Código | O que significa | O que fazer |
|---|---|---|
| 0 | Não foi possível autenticar o usuário do app (token expirado ou invalidado) | Gerar novo token |
| 190 | Token de acesso expirado | Gerar novo token |
| 3 e 10 | Permissão ausente ou removida | Conferir as permissões no depurador de token |
| 100 | Parâmetro não suportado ou escrito errado | Comparar com a referência do endpoint |
| 4 | Limite de chamadas do app atingido | Reduzir a frequência das chamadas |
| 80007 | Limite de chamadas da WABA atingido | Reduzir a frequência das chamadas |
| 368 | Conta restrita ou desativada por violação de política | Ver a política de aplicação e resolver a violação |
| 131031 | Conta bloqueada, ou dado enviado não confere (ex.: PIN de duas etapas errado) | Consultar a Health Status API |
| 131037 | Número 555 sem nome de exibição aprovado | Aprovar o nome de exibição |
| 133010 | Número não registrado na plataforma | Registrar o número e tentar de novo |
Se os erros 0 e 190 aparecem com frequência, o problema quase sempre é o tipo de token. Tokens temporários expiram; para produção, use um token permanente de usuário do sistema. Já o 368 e o 131031 pedem diagnóstico da conta, assunto do artigo número bloqueado na API do WhatsApp.
Um aviso sobre códigos antigos: listas que circulam na internet ainda citam o código 470. Ele não aparece na tabela atual da Cloud API. Se o seu sistema ainda trata 470, revise e passe a tratar pelos códigos atuais.
Como tratar erros no código
A regra prática é separar três grupos: o que se resolve sozinho com nova tentativa, o que pede outra mensagem e o que não deve ser reenviado.
// Classifica o erro da Cloud API pelo code
const RETRY = new Set([130429, 131056, 131000, 131016, 4, 80007]);
const USE_TEMPLATE = new Set([131047]);
const WAIT_24H = new Set([131049]);
const DO_NOT_RETRY = new Set([131026, 131050, 132001, 132007, 132015, 132016, 368]);
function decide(code) {
if (RETRY.has(code)) return 'retry_with_backoff';
if (USE_TEMPLATE.has(code)) return 'send_template';
if (WAIT_24H.has(code)) return 'retry_after_24h';
if (DO_NOT_RETRY.has(code)) return 'stop_and_flag';
return 'log_and_review';
}
function onStatus(status) {
if (status.status !== 'failed') return;
for (const err of status.errors || []) {
const action = decide(err.code);
console.log(status.id, status.recipient_id, err.code, err.error_data?.details, action);
}
}Três cuidados:
- Espera crescente nas novas tentativas. Para 130429 e 131056, tente de novo depois de 1, 2, 4, 8 segundos, com teto. Reenviar sem espera piora o limite.
- Grave
code,detailsefbtrace_id. Sem isso, o chamado com a Meta não anda. - A Meta só cobra mensagens entregues. Mesmo assim, cada falha de entrega para marketing pode indicar problema de base ou de qualidade. Acompanhe a taxa de
failedpor código ao longo do tempo.
Como isso funciona na Vectalk
Na Vectalk, os webhooks são os mesmos da Meta: o status failed chega com o array errors e os mesmos códigos desta tabela, então o mesmo tratamento serve. Os erros de autenticação da própria Vectalk são 401 (token ausente, inválido ou revogado) e 403 (token sem permissão para o recurso, como um token de organização chamando um endpoint que exige token de instância), documentados em Autenticação. Você também pode filtrar o histórico por status=failed no endpoint Listar Mensagens para revisar as falhas.
Para começar, crie sua conta em apps.vectalk.com.br/register. O panorama da plataforma está no guia da API oficial do WhatsApp.
Perguntas frequentes
O que é o erro 131047 no WhatsApp?
É o erro de “re-engajamento”: a mensagem não foi enviada porque passaram mais de 24 horas desde a última resposta do cliente. Fora da janela de atendimento, só templates aprovados podem ser enviados.
O erro 131026 significa que o número não tem WhatsApp?
Pode significar, mas não só. A Meta lista também usuário que não aceitou os termos mais recentes e versão desatualizada do app. A API não informa qual das causas ocorreu.
Mensagem com erro é cobrada?
A Meta informa que cobra apenas mensagens entregues, e não mensagens enviadas. Uma mensagem que termina em failed não chegou a ser entregue.
Devo reenviar mensagens com erro 131049?
Só depois de pelo menos 24 horas, conforme a orientação da Meta. Reenviar antes tende a falhar de novo.
Onde encontro a lista completa de códigos?
Na página Error codes da documentação da Meta, que também traz erros de criação de template, migração de número e da Marketing Messages API.
Fontes oficiais consultadas em 25/10/2026: Códigos de erro da WhatsApp Cloud API, Referência do webhook de status, Preços da plataforma do WhatsApp Business, Autenticação na documentação da Vectalk, Listar Mensagens na documentação da Vectalk, Webhooks na documentação da Vectalk.