Erros da API Oficial do WhatsApp: o que significam e o que fazer em cada caso
Referência aberta dos erros na API Oficial do WhatsApp — códigos 131xxx no envio, onboarding Embedded Signup, Cloud, Coexistência, WABA e permissões: mensagem Meta, causa e ação prática.
Conectar e operar na API Oficial do WhatsApp costuma travar em mensagens genéricas: “número não elegível”, “algo deu errado”, QR que não escaneia, número preso em WABA antiga, sync que nunca termina, permissão negada no Business Manager. A Meta quase nunca explica a causa raiz na tela.
Este guia é a referência aberta erro → causa → ação para quem implementa Embedded Signup, onboarda clientes ou opera WABA. Erros de conta, BM, pagamento, permissões e número valem para Cloud e Coexistência; QR, importação e app no celular são só Coexistência.
Escopo: envio (códigos 131xxx no webhook), onboarding (Embedded Signup) e operação pós-conexão. Templates rejeitados → guia de templates. Cloud ou Coexistência → comparativo. Selo azul → os três caminhos.
Pré-requisitos (Cloud e Coexistência)
Muitos “erros” são pré-requisito não atendido. Cheque antes de abrir ticket:
| Requisito | Detalhe |
|---|---|
| App (Coexistência) | WhatsApp Business 2.24.17+ (não o pessoal) |
| Atividade (Coexistência) | 7+ dias no app; ideal 30–60 |
| BM e Facebook | Página + Meta Business Manager com admin |
| WABA limpa | Número fora de outra WABA, BSP ou API não oficial |
| Nome da empresa | Defina antes de conectar (trava depois) |
Regra de ouro: número vindo de Z-API, Evolution ou similar → exclua no provedor anterior, use o Business App com conversas reais 1–2 meses, só então tente a API Oficial de novo. Reconectar no dia seguinte quase sempre falha.
Tabela mestra: erro → ação
| Mensagem / sintoma | Causa provável | O que fazer | Modelo |
|---|---|---|---|
| “Mais atividade no WhatsApp Business App é necessária.” | Uso insuficiente no app | Conversas reais 7–60 dias. Não exclua e re-registre o número. | Coex. |
| Email: não elegível para Coexistence Onboarding | Bloqueio de política | Número alternativo. Revise política comercial. | Coex. |
| “Este número está registrado em uma conta WhatsApp existente.” / “Esse número já está registrado…“ | WABA/BSP/API anterior | Desconecte no provedor → Business App → 1–2 meses de uso → tente de novo. | Ambos |
| “Esse número de telefone já existe na sua lista de números.” | Já na WABA atual | Selecione o número existente no fluxo. | Ambos |
| “O número de telefone foi bloqueado.” | Restrição Meta | Gerenciador do WhatsApp ou ticket Meta. | Ambos |
| “Número máximo de telefones vinculados…“ | Limite na WABA | Remova inativos ou use outra WABA/BM. | Ambos |
| “Nome verificado viola as diretrizes…“ | Nome fora da política | Ajuste conforme diretrizes de nome. | Ambos |
| “Verificação do nome já está em andamento.” | Nome em análise | Aguarde antes de seguir o signup. | Ambos |
| QR Code não aparece ou não escaneia | App velho, fluxo errado | App 2.24.17+, cache do browser, Configurações → Conta → Plataforma comercial. | Coex. |
| Importação travou / sync eterno | Rede ou volume alto | App aberto, Wi-Fi, até 6 h. Falhou → reescaneie o QR. | Coex. |
| Erro ao vincular à Página do Facebook | Página ou permissão | Admin no BM e na Página; dados completos. | Ambos |
| Windows/WearOS não aparecem na API | Dispositivo não suportado | Só WhatsApp Web e Mac. | Coex. |
| Nome da empresa não altera depois | Comportamento pós-coex | Ajuste antes do QR; depois só suporte Meta. | Coex. |
| “Limitamos a frequência…“ | Rate limit | Pare tentativas; conta Facebook madura. | Ambos |
| Sem permissão para anunciar | Conta restrita | Troque de conta Facebook com admin no BM. | Ambos |
| Conta Facebook muito nova | Conta recente | 30+ dias de histórico ou aguarde e retome. | Ambos |
| Limite de empresas criadas | Limite de BMs | Use BM existente. | Ambos |
| Conta de pagamento desabilitada | Billing pendente | Regularize no Suporte Meta. | Ambos |
| Sem permissão para criar WABA | Usuário sem admin | Controle total ou admin WhatsApp no BM. | Ambos |
| “Algo deu errado. Entre em contato com o suporte.” | Erro genérico Meta | 15–30 min, cache, retry. Persiste → ticket com print + horário UTC. | Ambos |
| Escolheu “Conectar número de telefone” | Fluxo PIN / MM Lite | Volte e escolha “Conectar seu aplicativo WhatsApp Business existente”. | Coex. |
| Respostas duplicadas | App + bot da API | Desligue saudação/ausência no app antes do chatbot. | Coex. |
| Conexão caiu semanas depois | App 14+ dias fechado | Abra o Business App a cada 14 dias (Coexistence Guidelines). | Coex. |
Coexistência: notas rápidas
QR (checklist): app atualizado → cache do browser → fluxo Plataforma comercial → boa iluminação → aguarde 5–15 min → reinstalar app só como último recurso.
Sync: contatos entram sempre; conversas 1:1 até 6 meses (mídias ~2 semanas); grupos não vão para a API. Pulou importação → precisa desvincular e refazer o onboarding.
Desconectar: app → Configurações → Conta → Plataforma de Negócios → Desconectar. Não desinstale o app para “desconectar”.
Códigos de erro no envio (131xxx)
Quando a mensagem não entrega, a Meta devolve errors[] no webhook de status (code). Persista o código no seu produto (dashboard, alerta, retry).
| Código | O que significa | O que fazer |
|---|---|---|
| 131042 | Pagamento | Regularize billing no BM (cartão, limite, moeda). |
| 131026 | Indeliverável | Número inválido ou fora do WhatsApp. Confirme E.164. |
| 131049 | Saúde do ecossistema | Reduza marketing frio; veja quality rating. |
| 131047 | Janela 24h fechada | Só template aprovado — veja janela e categorias. |
| 130472 | Experimento Meta | Destinatário em grupo de teste. Sem workaround. |
| 131048 | Spam rate limit | Pause campanhas; monitore quality rating. |
| 131031 | WABA bloqueada | Gerenciador do WhatsApp → ticket Meta com WABA ID. |
| 131053 | Mídia | Tipo, tamanho ou codec fora do spec. |
| 131050 | Opt-out marketing | Remova da campanha; só serviço permitido. |
| 131000 | Genérico | Retry com backoff; ticket com message_id e horário UTC. |
Onde aparece: webhook messages → statuses → errors.
Quando escalar para a Meta
- Número bloqueado sem caminho no Gerenciador
- Inelegibilidade permanente (email de política) no único canal do cliente
- Erro genérico 24h+ com pré-requisitos ok
- Pagamento “desabilitado” sem pendência visível
Leve no ticket: print da mensagem, horário UTC, WABA ID, versão do app, país do número, confirmação de que não há WABA paralela.
FAQ
Cobre template e envio? Sim: 131xxx aqui; reprovação de template no guia de templates.
WhatsApp pessoal funciona em Coexistência? Não. Só Business App.
API não oficial impede? Sim, enquanto o número estiver registrado lá. Limpe, resfrie, tente depois.
Mapa interativo com esses erros? Membros têm o mapa Meta API com modais por nó. Este artigo é a versão aberta e pesquisável.
Referências: WhatsApp Cloud API, Central de Ajuda WhatsApp Business, *WhatsApp Coexistence Guidelines. Regras mudam — valide na documentação oficial antes de prometer prazo ao cliente.*
Conteúdo da comunidade WhatsApp Founders 🇧🇷 — independente, sem vínculo oficial com o WhatsApp ou a Meta.