❓ O que é o erro 9001004?
O erro 9001004 é um código de validação prévia (pre-flight) que funciona como um mecanismo de segurança integrado na plataforma.
É gerado automaticamente ao tentar enviar um template ou executar um fluxo quando o sistema detecta que o contato não possui um número de telefone ou um identificador de Meta válido (BSUID) associado a esse canal. Essa validação antecipada é crucial porque evita que se realizem requisições com falha aos servidores do Meta.
🎯 Cenários de Disparo
O erro pode ocorrer em três processos operacionais principais dentro da plataforma:
Envios de Campanhas: Ocorre comumente se você baixar uma lista de contatos e tentar enviar uma campanha através de um número que não pertence ao mesmo Business Manager, o que invalida o identificador do cliente.
Tipificação de Conversas: Ao realizar uma tipificação no WhatsApp, o sistema avalia os dados do cliente. Se o contato não tem telefone visível e seu BSUID não pertence ao negócio do canal em uso, o processo é bloqueado antes de enviar a requisição ao Meta.
Bot de Mensagem Entrante (templateExec): Quando o bot processa uma mensagem para disparar um template, ele interrompe a chamada ao Meta se não conseguir resolver a identidade do cliente no portfólio, e registra o erro diretamente no log do fluxo.
⚙️ Processo de Validação em Cascata
Para evitar envios com erro, o sistema não rejeita o contato imediatamente, mas executa uma validação lógica estruturada passo a passo:
Passo 1 - Iniciar envio: O envio é disparado (ex. sendCampaignTask) e o lote de contatos é capturado.
Passo 2 - Iteração individual: O sistema prepara o envio avaliando o cliente um por um (executePerClient).
Passo 3 - Resolução em cascata: O validador tenta resolver a identidade do destinatário através de uma busca exata e sequencial:
Primeiro busca o telefone.
Se não há telefone, busca o BSUID do canal.
Se não coincide, busca o Parent BSUID. 👉 Se ao final dessa cascata nenhuma identidade válida for encontrada, o erro 9001004 é disparado e bloqueia o envio para esse registro em particular.
💬 Mensagens de Erro Contextuais
Para facilitar a compreensão do problema pelo usuário, o sistema possui um catálogo centralizado e traduzido (espanhol, inglês, francês e português) que exibe uma mensagem descritiva adaptada ao módulo onde ocorreu a falha:
No Módulo de Tipificação: "Não se conta com telefone nem identificador de Meta válido para o cliente, no canal em que está sendo atendida esta conversa."
No Módulo de Campanhas: "Não se conta com telefone nem identificador de Meta válido para o cliente, no canal configurado para esta campanha."
📊 Rastreabilidade e Encerramento de Ciclo
O tratamento deste erro foi projetado para manter suas métricas de sucesso e falhas completamente precisas e auditáveis:
Painel de Health: Os erros detectados na validação prévia são visualizados e contabilizados diretamente no painel de saúde do disparador.
Encerramento de Ciclo Seguro: Ao disparar o erro, o status do envio passa imediatamente para FAILED (Falha), encerrando o ciclo de rastreamento de forma equivalente como se a falha tivesse ocorrido com um número de telefone tradicional.
Relatórios CSV precisos: Ao exportar os resultados, o arquivo CSV inclui uma estrutura fixa de 7 colunas (
clientId,phone,bsuid,errorCode,error,date,template). O sistema incorpora as linhas com o código 9001004, deixando corretamente vazio o campo do número de telefone nos casos onde você só conta com um BSUID inválido.
Proteja a reputação de sua linha e otimize seus envios! 🚀
O erro 9001004 não é uma falha do sistema, mas um escudo protetor que valida seus destinatários antes de tocar nos servidores do Meta, garantindo que sua reportagem seja precisa e seus recursos sejam utilizados apenas em contatos alcançáveis. ✅