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 da Meta, causa e ação prática.
Conectar e operar na API Oficial do WhatsApp trava em mensagem genérica.
“Número não elegível.” “Algo deu errado.” QR que não escaneia. Número preso em WABA (WhatsApp Business Account) antiga. Sync que nunca termina. Permissão negada no Business Manager.
A Meta quase nunca explica a causa raiz na tela.
E o erro que mais custa dinheiro não é nenhum código 131xxx. É o onboarding que falha três vezes seguidas porque o número ainda carregava vínculo com API não oficial. Evolution ou Z-API ontem, Cloud API hoje, Meta nega. A tela não diz nada disso.
Este guia é a referência aberta erro → causa → ação para quem implementa Embedded Signup, onboarda cliente ou opera WABA.
Erro de conta, BM, pagamento, permissão e número vale 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)
Muito “erro” é 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 por 1 a 2 meses, só então tente a API Oficial de novo. Reconectar no dia seguinte quase sempre falha.
Diga isso ao cliente antes que ele pergunte. Não existe sair da API não oficial hoje e entrar na Oficial amanhã.
A tentativa do dia seguinte falha. A de dois dias depois também. O que destrava não é insistência. É tempo de uso real no Business App.
Tabela mestra: erro → ação
Na coluna Modelo, Coex. = Coexistência.
| 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. Guarde 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.