Solucione erros de conexão entre WhatsApp Business API e Pluga com este guia completo de troubleshooting, incluindo QR Code, elegibilidade e integração.
Ao conectar o WhatsApp Business API à Pluga, você pode encontrar diferentes erros relacionados à autenticação, elegibilidade do número ou configurações da Meta. Este guia reúne as principais falhas e suas soluções práticas.
Nesta página você encontra:
- Erro ao ler QR Code no WhatsApp Business
- Número não é elegível por pouco tempo de uso
- Funcionalidade indisponível em determinados países
- Erro por integração anterior com WhatsApp Business API
- WhatsApp no Windows não exibe mensagens
- Meu nome de exibição foi rejeitado, porque motivo e o que fazer?
- Erro: "You've reached the maximum number of ad account allowed for your business"
-
Outros erros comuns da Meta e soluções
Erro ao ler QR Code no WhatsApp Business
Durante a etapa de leitura do QR Code no processo de conexão com o WhatsApp Business API, podem ocorrer dois erros principais:
- Exibição da mensagem "QR Code inválido".
- O sistema retorna automaticamente para a etapa anterior (geralmente a do PIN) sem explicação.
Esses problemas podem acontecer por diferentes fatores:
- Verificação em duas etapas: caso esteja habilitada, o sistema exigirá o PIN de seis dígitos. Se o PIN não for informado corretamente ou expirar, o processo será interrompido.
- Problemas de rede ou conexão: internet instável no celular principal ou no dispositivo que executa o Embedded Signup pode gerar falhas de sincronização.
- Sincronização do aplicativo: se o app WhatsApp Business estiver desatualizado, corrompido ou com processos em segundo plano ativos, o vínculo pode falhar. A Meta recomenda manter o app aberto durante o processo.
- Permissões ou conta: erros menos comuns relacionados ao Meta Business Manager ou à Página do Facebook associada podem afetar a conexão.
- Timeouts ou erros do sistema: chamadas de API podem falhar ou sofrer atrasos temporários nos servidores da Meta.
- Atualize o app WhatsApp Business para a versão 2.24.17 ou superior.
- Verifique se a câmera do celular está limpa e funcionando corretamente.
- Utilize a opção Conectar com número de telefone em vez de QR Code. Caminho: menu → Dispositivos conectados → Conectar dispositivo → Conectar com número de telefone.
- Associe o número de telefone do WhatsApp Business diretamente à conta no Meta Business Manager.
- Tente testar em um smartphone diferente com o WhatsApp Business: Embora a Meta não forneça uma recomendação oficial para essa etapa, alguns usuários da Pluga conseguiram resolver problemas ao trocar para outro dispositivo durante a autenticação.
Número não é elegível por pouco tempo de uso
A Meta pode bloquear a coexistência de número no app e na API quando identifica pouco histórico de uso. Já houve casos com números ativos há apenas um mês.
- Construa histórico de uso: utilize o WhatsApp Business ativamente por pelo menos 7 dias (ideal: 1 a 2 meses).
- Evite re-cadastrar: excluir e cadastrar novamente pode zerar o histórico.
- Verifique uso anterior na API: se o número já foi integrado, será necessário removê-lo do Meta Business, registrar novamente no app e criar histórico antes de tentar reconectar.
Funcionalidade indisponível em determinados países
Em alguns países a integração com o WhatsApp Business API ainda não é permitida. Ao tentar usar um número de país inelegível, será exibida mensagem de indisponibilidade.
Erro por integração anterior com WhatsApp Business API
Se o número já foi integrado ao WhatsApp Business API em outro provedor, a Meta não permite nova conexão sem antes remover o vínculo anterior.
WhatsApp no Windows não exibe mensagens
Em alguns casos, conversas antigas deixam de aparecer no aplicativo para Windows, já que a Meta não oferece suporte de coexistência nessa versão.
- Utilize versões compatíveis como WhatsApp Web ou WhatsApp para Mac.
- Acompanhe atualizações da Meta que possam corrigir a limitação.
Nome de exibição rejeitado: motivos e soluções
Existem regras para nomes de exibição que são aceitos pela Meta, você pode verificar os motivos de rejeição neste link: Diretrizes para nomes de exibição na Plataforma do WhatsApp Business
Refaça a sua autenticação com um nome de exibição aceito pelas regras da Meta.
Erro: limite de contas de anúncios atingido
Durante o processo de conexão de um número de telefone à API do WhatsApp Business, pode aparecer a seguinte mensagem:
Essa mensagem indica que o Business Manager (conta comercial Meta) atingiu o limite máximo de contas de anúncios (ad accounts) permitido. Mesmo que o erro pareça relacionado a anúncios, ele bloqueia a criação automática dos ativos necessários para ativar o WhatsApp Business API.
-
Acessar o Business Manager
Vá para https://business.facebook.com/settings. Selecione o Business Manager vinculado à integração do WhatsApp Business. -
Verificar contas de anúncios existentes
No menu lateral, clique em Contas → Contas de anúncios. Verifique a lista de contas de anúncios associadas à empresa. Caso o botão "Adicionar" → "Criar nova conta de anúncios" esteja desativado ou exiba erro, o limite foi atingido. Se possível, remova contas inativas ou não utilizadas para liberar espaço. -
Verificar a verificação da empresa
No menu lateral, acesse Central de segurança (Security Center) ou vá direto para https://business.facebook.com/settings/security. Em Verificação da empresa, confira o status: Verificado → Tudo certo ✅ Não verificado → Clique em "Iniciar verificação" e siga as etapas: informe nome legal da empresa e CNPJ, adicione endereço comercial e envie os documentos solicitados.
-
Excluir contas de anúncios antigas
Acesse https://business.facebook.com/settings/ad-accounts. Selecione contas de anúncios que não estão em uso. Clique em Remover ou Encerrar conta de anúncios. Tente novamente conectar o número do WhatsApp após alguns minutos. -
Verificar a empresa (Business Verification)
A verificação pode aumentar automaticamente o limite de ad accounts. Após completar o processo de verificação, aguarde até 24h e refaça o onboarding do WhatsApp Business. -
Solicitar aumento de limite à Meta
Acesse o Suporte da Meta Business. Selecione Gerenciador de Anúncios → Problemas com contas de anúncios. Envie uma solicitação com a seguinte mensagem:"Hello, I'm trying to connect a WhatsApp Business number through the Embedded Signup process, but I received the message "You've reached the maximum number of ad account allowed for your business." Could you please increase our ad account limit or help us complete this onboarding? Our business is verified and in good standing." -
Realizar um pagamento de anúncios (opcional)
Fazer o primeiro pagamento em uma conta de anúncios ativa pode ajudar a aumentar o limite automaticamente, demonstrando atividade e confiabilidade.
Aguarde algumas horas (até 24h) após qualquer alteração no Business Manager. Refaça o processo de autenticação da sua conta na Pluga.
Outros erros comuns da Meta e soluções
A seguir, listamos os principais códigos de erro retornados pelo WhatsApp Business API, com explicações e como resolver:
| Código – Mensagem | Detalhamento | O que fazer |
|---|---|---|
| #200 – You do not have the necessary permissions | O app não tem permissão para enviar em nome do WABA. | Refaça o Embedded Signup garantindo acesso total no BM → WhatsApp Accounts. |
| #10 – Application does not have permission for this action | O app não possui o escopo necessário. | Reconecte o app ao WABA com permissões adequadas. |
| #33 – The requested phone number has been deleted |
O número foi removido do WABA ou o phone_number_id está inválido.
|
Verifique no WhatsApp Manager se o número está ativo. |
| 131010 – Phone number not registered | Número não registrado na plataforma. | Cadastre o número no WABA correto. |
| 133015 – Please wait before registering | Remoção ainda em andamento. | Aguarde alguns minutos/horas antes de tentar novamente. |
| 133000 – Incomplete deregistration | Desregistração pendente. | Finalize a remoção antes de registrar novamente. |
| 131047 – Re-engagement required | Envio após 24h sem interação, permitido apenas via template. | Reabra a conversa com template aprovado. |
| 131052 – Media download error | Falha ao baixar a mídia (link inválido/expirado). | Verifique a disponibilidade do arquivo. |
| 131053 – Media upload error | Erro ao enviar mídia. | Valide formato e tamanho antes de reenviar. |
| 131051 – Unsupported message type | Tipo de mensagem não suportado. | Use tipos válidos (texto, imagem, template). |
| 131048 – Spam / rate-limit | Restrição por baixa qualidade ou denúncias. | Melhore opt-in e reduza disparos. |
| 130497 – Business restricted by country | Restrição de país. | Use número elegível em país suportado. |
| #368 – Temporarily blocked | Número bloqueado por violação de política. | Revise práticas e aguarde liberação. |
| 131031 – Account locked | Conta bloqueada. | Corrija pendências no BM. |
| 131057 – Account in maintenance mode | Conta em manutenção. | Aguarde término ou acione suporte. |
| #2 / 503 / 131016 – Service unavailable | API temporariamente indisponível. | Tente novamente mais tarde. |
| 131021 – Recipient cannot be sender | Tentativa de envio para o próprio número. | Teste com outro destinatário. |
Dúvidas?
Caso ainda tenha dúvidas, é só solicitar um atendimento que nosso time de suporte entrará em contato dentro de algumas horas ;)