Erros da Cloud API do WhatsApp: códigos e soluções

A resposta da Cloud API quando algo falha é curta e pouco generosa: um número e uma frase em inglês que costuma descrever o sintoma, não a causa. Message undeliverable pode significar cinco coisas diferentes, e nenhuma delas está escrita ali.

Esta é a tradução. Os códigos estão agrupados por família, porque diagnosticar por família é mais rápido do que decorar número por número.

Onde o código aparece

Todo erro vem no corpo da resposta HTTP, dentro de error. O campo que importa é code; o error_data.details costuma trazer a informação real, e é o que a maioria dos logs joga fora.

{
  "error": {
    "message": "(#131047) Re-engagement message",
    "type": "OAuthException",
    "code": 131047,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Message failed to send because more than 24 hours have passed since the customer last replied to this number."
    },
    "fbtrace_id": "A1bCdEfGhIjKlMnOpQr"
  }
}

Registre code, details e fbtrace_id juntos. Log que guarda só a mensagem em inglês transforma um diagnóstico de dois minutos numa tarde de tentativa e erro.

Família 1: a janela de 24 horas

É a causa mais comum de mensagem que não sai, e a que mais confunde quem está começando — porque o mesmo código funciona de manhã e falha à tarde.

Família 2: templates

A segunda maior fonte de falha, e a que mais aparece em produção — porque template funciona no teste e quebra quando as variáveis reais chegam.

O 132015 merece leitura diferente dos outros: ele não é erro técnico, é sinal de que as pessoas estão bloqueando. Tratá-lo como bug e reenviar acelera o caminho para a restrição do número. O que fazer está em qualidade do número.

Família 3: credencial e identificador

Família 4: conta, limite e política

131042 é o erro mais frustrante da lista: tudo está tecnicamente correto e nada sai, porque o cartão da conta comercial venceu. Vale um alerta próprio no seu monitoramento.

Família 5: mídia

As faixas de envio, que produzem outra família de falhas, estão em limites de envio.

O diagnóstico, em ordem

Como evitar metade destes erros

1. 1Sanitize toda variável de template. Remova quebra de linha, tabulação e espaços seguidos, e trunque o tamanho. Resolve 132007, 132005 e boa parte do 132000.
2. 2Nunca envie variável vazia. Se o dado não existe, use um valor padrão — string vazia continua contando como parâmetro.
3. 3Guarde o horário da última mensagem de cada cliente. Antes de enviar, compare com agora: menos de 24h, texto livre; mais, template. Elimina o 131047 na origem.
4. 4Use token de usuário do sistema desde o primeiro dia de produção. O temporário só serve para o primeiro teste.
5. 5Implemente repetição com espera crescente para 130429 e 131016 — são transitórios, e insistir na mesma velocidade piora.
6. 6Monitore 131042 e 132015 como alerta, não como log. Os dois param a operação em silêncio.

Um erro que não é erro

Vale registrar porque gera chamado toda semana: mensagem entregue e não lida não é falha. O webhook de status entrega sent, delivered e read em momentos diferentes, e read só chega se o destinatário tiver a confirmação de leitura ligada. Ausência de read não significa que a mensagem não chegou — significa que você não tem como saber.

Perguntas frequentes

Resumo

• Leia error.code e error_data.details — a mensagem em inglês descreve o sintoma, não a causa.
• 131047 é janela fechada: fora dela só template.
• 132000 quase sempre é variável vazia contando como parâmetro.
• 190 e 33 são credencial e identificador — os dois erros de quem está começando.
• 131042 e 132015 param a operação em silêncio: monitore como alerta.
• Guarde o fbtrace_id. Sem ele, o suporte da Meta não investiga.