Erros Comuns API Oficial

100 Parâmetro inválido ou permissão insuficiente

Acontece quando a requisição enviada à API tem algum dado incorreto ou quando o aplicativo não tem permissão para executar a ação. Também aparece ao tentar acessar um recurso que não existe.

• Parâmetros obrigatórios ausentes, incompletos ou em formato inválido — por exemplo, um ID que não existe;
• Tentativa de acessar um recurso indisponível para o aplicativo;
• Permissões insuficientes para enviar mensagens ou acessar determinados dados;
• Links malformados dentro da mensagem, que não atendem aos requisitos da Meta.

• Confirme que todos os parâmetros obrigatórios estão presentes e no formato correto;
• Revise as permissões do aplicativo no painel da Meta e conceda o que estiver faltando;
• Valide se os recursos e IDs informados realmente existem;
• Se a mensagem tiver links, teste as URLs antes do envio.

130472 Experimento da Meta com mensagens de marketing

A Meta seleciona cerca de 1% dos números conectados à Cloud API no mundo para participar de um experimento controlado, que avalia o impacto das mensagens de marketing na experiência do usuário. Para os números incluídos, o envio de modelos da categoria Marketing pode ser limitado ou bloqueado temporariamente.

Isso acontece mesmo com a conta configurada corretamente, com saldo disponível, templates aprovados e sem nenhuma infração às políticas.

• Use modelos da categoria Utilidade — o bloqueio mira mensagens de Marketing, então confirmações de pedido, boletos e lembretes de agendamento costumam passar;
• Aguarde o cliente iniciar — a restrição se aplica ao envio partindo da empresa. Se o cliente mandar mensagem primeiro, abre a janela de 24 horas e a conversa flui normalmente;
• Use outro canal — em casos urgentes, ligue ou mande e-mail pedindo que o cliente inicie a conversa no WhatsApp.

130497 Restrição geográfica por país mal configurado

Indica que a conta está sujeita a uma restrição geográfica de envio. Normalmente acontece porque a Meta não conseguiu validar a localização da empresa — e, ao contrário do que se imagina, ela não deduz o país pelo prefixo do número. Se o campo País estiver vazio ou errado nas informações da empresa, o sistema aplica restrições de envio entre países mesmo quando a conversa acontece dentro do mesmo país.

1. Acesse o Gerenciador de Negócios da Meta;
2. Vá em Configurações do negócio → Informações da empresa;
3. Localize o campo País e confira se está preenchido corretamente (Brasil, por exemplo);
4. Se estiver vazio ou incorreto, clique em Editar, selecione o país e salve;
5. Aguarde a propagação da alteração — o envio tende a normalizar sozinho depois disso.

131000 Erro desconhecido / falha técnica temporária

Falha no processamento do envio pela API da Meta. Costuma estar ligado a problemas momentâneos de comunicação entre sistemas, instabilidade nos serviços da Meta ou configuração incorreta da integração.

• Verifique se há instabilidade ou manutenção em andamento nos serviços da Meta;
• Confirme que a conexão de internet está funcionando normalmente;
• Tente enviar de novo depois de alguns instantes — na maioria dos casos o erro é passageiro.

131026 Número do destinatário não tem WhatsApp

A mensagem não pôde ser entregue porque o número informado não tem conta ativa no WhatsApp.

• O número realmente não tem WhatsApp;
• O cliente trocou de número e não avisou;
• Erro de digitação — dígitos a mais, a menos ou formato incorreto;
• Conta desativada pelo próprio usuário.

1. Confira o número — formato internacional com código do país (+55) e o nono dígito, quando aplicável;
2. Teste se o número tem WhatsApp — tente iniciar uma conversa pelo aplicativo ou por um link wa.me;
3. Teste com outro número — envie o mesmo modelo para um número que você sabe estar ativo. Se funcionar, o problema é do número original; se não funcionar, investigue o modelo ou a configuração da conta.

131031 Conta restrita ou bloqueada pela Meta

A conta do WhatsApp Business foi restringida ou bloqueada, normalmente por violação de alguma política de uso. A Meta limita ou suspende o envio até que a situação seja analisada.

• Conteúdo fora das diretrizes ou comunicação não autorizada pelos destinatários;
• Volume elevado de bloqueios e denúncias de spam;
• Uso considerado suspeito — disparos em massa ou automações agressivas.

1. Acesse o Gerenciador de Negócios da Meta;
2. Clique no ícone de menu na barra lateral esquerda;
3. Abra a Página Inicial do Suporte para Empresas;
4. Verifique notificações, alertas ou mensagens da Meta sobre a conta.

• Revise as Políticas Comerciais e de Mensagens e evite conteúdos que possam ser lidos como spam;
• Responda às notificações da Meta — ela costuma pedir informações adicionais ou ajustes nas práticas de envio;
• Reduza disparos para listas grandes de contatos sem interação recente e garanta que o opt-in esteja coletado e documentado.

131042 Falha no processamento do pagamento

A Meta não conseguiu processar a cobrança no cartão cadastrado no portfólio empresarial. Na maioria dos casos o problema está no próprio sistema de cobrança da Meta, e o débito falha mesmo com o cartão válido e ativo.

1. Confira os dados do cartão no Gerenciador de Negócios e verifique se há limite disponível;
2. Tente pagar manualmente — em Contas → Contas do WhatsApp → Configurações de pagamento, veja o saldo pendente e faça a cobrança. Se o valor total não passar, tente um valor ligeiramente menor;
3. Atualize ou adicione outro cartão no mesmo caminho, clicando em Adicionar forma de pagamento. Depois aguarde alguns minutos para a Meta processar.

131047 Janela de 24 horas encerrada

A empresa tentou enviar uma mensagem depois de 24 horas da última mensagem do cliente. Passado esse prazo, só é possível retomar o contato com um modelo de mensagem aprovado pela Meta. A regra existe para evitar comunicação não solicitada.

Envie um modelo aprovado. Assim que o cliente responder, a janela de 24 horas reabre e a conversa segue normalmente.

131048 Parâmetro ausente ou limite de qualidade atingido

Junta dois cenários: problema na estrutura da mensagem ou limitação aplicada por qualidade e volume de envio.

• Campos obrigatórios ausentes ou em formato incorreto;
• Classificação de qualidade baixa, geralmente por bloqueios e denúncias de usuários;
• Volume muito alto de mensagens em um curto intervalo.

• Revise os campos obrigatórios e o formato dos dados;
• Reduza o volume de envios a partir do mesmo número;
• Consulte o status de qualidade do número no Gerenciador do WhatsApp;
• Evite mensagens idênticas ou muito frequentes.

131049 Limite de marketing por destinatário

Aparece ao tentar iniciar ou reiniciar uma conversa com um modelo de mensagem. Não é falha do Chat C&M: a Meta identificou que aquele número recebeu muitas mensagens de marketing em pouco tempo e bloqueou temporariamente novos envios dessa categoria para ele.

• Não reenvie a mesma mensagem imediatamente;
• Envie uma mensagem do tipo Utilidade, se fizer sentido para o contexto;
• Aguarde um período maior antes de tentar de novo — o bloqueio pode durar de algumas horas a alguns dias.

• Varie os tipos de mensagem em vez de usar só marketing;
• Espace os envios para o mesmo número;
• Aguarde o desbloqueio automático, que acontece sem necessidade de solicitação.

131051 Tipo de conteúdo não suportado pela API

Aparece quando o contato envia um conteúdo que a API oficial não consegue processar. É comportamento esperado e definido pela Meta — não é algo que o Chat C&M possa alterar. A conversa não se perde: todas as demais mensagens continuam no histórico do atendimento.

• Reações a mensagens (os emojis de reação);
• Figurinhas animadas ou stickers personalizados incompatíveis;
• Áudios temporários e formatos específicos de nota de voz;
• Arquivos em formatos muito recentes, ainda não suportados;
• Mensagens de bots ou automações externas com recursos incompatíveis.

• Avise o cliente que aquele formato não é compatível com a integração oficial;
• Peça que ele reenvie como texto, imagem, áudio padrão ou documento;
• Se for recorrente, oriente o contato a evitar reações e figurinhas animadas.

131056 Volume de envios para o mesmo contato

Ocorre principalmente quando muitas mensagens de marketing vão para o mesmo contato em pouco tempo. A Meta pausa automaticamente novos envios dessa categoria para aquele destinatário. O Chat C&M segue funcionando normalmente — a restrição é por número de destino.

• Reduza a quantidade de mensagens de marketing por contato;
• Alterne com mensagens do tipo Utilidade, que têm regras mais flexíveis;
• Acompanhe os status de entrega e, se os bloqueios forem frequentes, diminua o volume e aguarde o desbloqueio automático.

131060 Mensagem sem conteúdo em coexistência e CTWA

Aparece principalmente em números que operam em coexistência e recebem contatos vindos de anúncios Click-to-WhatsApp. É uma limitação conhecida da infraestrutura do WhatsApp.

Quando um cliente inicia conversa com um número comercial, o aplicativo precisa exibir antes uma mensagem de sistema — o chamado aviso azul — informando que a conversa é gerenciada por um serviço da Meta. Se o cliente escreve antes desse aviso aparecer, o WhatsApp ainda trata a conversa como um chat comum do aplicativo. O evento de envio chega, mas o conteúdo da mensagem não é compartilhado com a API oficial — e a mensagem entra no histórico vazia.

• O usuário clica no anúncio e a mensagem pré-definida sai quase instantaneamente;
• Costuma ser o primeiro contato com aquele número, sem o contato salvo na agenda;
• A criptografia e a identificação da conversa comercial ainda estão sendo processadas.

Aparelhos mais antigos, conexão instável e alto volume simultâneo de mensagens parecem aumentar a incidência, embora a Meta não confirme oficialmente todos os fatores.

132001 Modelo de mensagem não existe

A API não localizou o modelo solicitado na base de templates da Meta.

• Modelo excluído no Gerenciador do WhatsApp;
• Nome do modelo informado incorretamente;
• Modelo ainda em análise pela Meta;
• Modelo reprovado, e portanto indisponível até ser ajustado e reaprovado.

• Peça a um usuário administrador que sincronize os modelos de mensagem com a Meta;
• Se o modelo não existir mais, crie um novo e aguarde a aprovação;
• Se estiver reprovado, revise o conteúdo e reenvie para análise;
• Siga as diretrizes da Meta para modelos, evitando novas reprovações.

135000 Falha ao enviar modelo de mensagem

Acontece quando o atendente tenta enviar um modelo durante o atendimento e o envio falha. Geralmente é inconsistência de sincronização: o modelo pode estar aprovado na Meta, mas desatualizado no Chat C&M.

Comece pela sincronização dos modelos de mensagem com a Meta — ação que precisa ser feita por um usuário administrador. Se o problema continuar:

1. Localize o modelo no painel de Modelos de Mensagem de Atendimento;
2. Duplique o modelo que apresentou o erro, mantendo ou ajustando o conteúdo;
3. Envie a cópia para aprovação da Meta e aguarde;
4. Depois de aprovado, teste o envio com o modelo duplicado.