Como em qualquer comunicação via API, durante as requisições podem ocorrer códigos de erro, que indicam desde falhas de autenticação e permissões até problemas operacionais ou de configuração.
Compreender o significado desses códigos é essencial para identificar a origem do problema com mais rapidez, agir de forma assertiva e reduzir impactos no atendimento aos clientes.
Neste artigo, reunimos os principais códigos de erro retornados pela API Oficial da Meta para facilitar o diagnóstico e a resolução de problemas.
💡 Como a lista é longa,indicamos utilizar o atalho CTRL + F para localizar a numeração do erro que procura rapidamente. 😉 |
Erros de integridade
Código | Detalhes | Possíveis motivos e soluções | Código de status HTTP |
Bloqueado temporariamente por violações de políticas | A conta do WhatsApp Business associada ao app foi restringida ou desabilitada por violar uma política da plataforma. | Consulte o documento Aplicação das políticas para saber mais sobre as violações das políticas e como solucioná-las. |
Proibido |
A conta comercial está impedida de enviar mensagens a usuários neste país. | A conta do WhatsApp Business está impedida de enviar mensagens para usuários em determinados países. | Para ver quais são os países permitidos para o envio de mensagens na categoria da sua empresa, consulte a Política de Mensagens do WhatsApp Business. |
Proibido |
A conta foi bloqueada | A conta do WhatsApp Business associada ao app foi restringida ou desabilitada por violar uma política da plataforma ou não foi possível verificar os dados incluídos no pedido em relação ao conjunto de dados na conta do WhatsApp Business (por exemplo, o pin de duas etapas incluído no pedido está incorreto). | Consulte o documento Aplicação das políticas para saber mais sobre as violações das políticas e como solucioná-las. |
|
Erros de criação de modelo
Erro | Descrição | Solução possível |
| Um campo do modelo excedeu o limite máximo de caracteres permitido. | Verifique a mensagem de erro para ver detalhes específicos sobre o campo afetado e os limites de caracteres correspondentes. |
| O cabeçalho da mensagem contém formatação inválida. | Verifique a mensagem de erro para ver detalhes sobre a formatação válida. |
| O corpo da mensagem contém formatação inválida. | Verifique a mensagem de erro para ver detalhes sobre a formatação válida. |
| O rodapé da mensagem contém formatação inválida. | Verifique a mensagem de erro para ver detalhes sobre a formatação válida. |
| Esse modelo contém muitas variáveis para sua extensão. Reduza o número de variáveis ou aumente a extensão da mensagem. | Verifique a mensagem de erro para ver detalhes sobre a formatação válida. |
| As variáveis não podem estar no início ou no fim do modelo. | Verifique a mensagem de erro para ver detalhes sobre a formatação válida. |
Erros de envio de modelo
Erro | Descrição | Solução possível |
| Você excedeu o máximo de modelos de mensagem permitidos para esta conta do WhatsApp Business. | Uma conta do WhatsApp Business pode ter até 250 modelos de mensagem. Consulte Limites de modelos. |
Erros de migração de telefone
Erro | Descrição | Solução possível |
| Só é possível baixar o certificado depois da confirmação da propriedade do número de telefone que está sendo migrado. | Para baixar o certificado e dar continuidade ao registro, registre e verifique o número. |
| A autenticação em duas etapas deve estar desabilitada para esse número de telefone. | Nas configurações do Gerenciador de Negócios do WhatsApp, desative a verificação em duas etapas. |
| O número de telefone que você está tentando migrar já está presente na sua conta do WhatsApp. | Tente novamente com um número de telefone que ainda não esteja presente na sua conta do WhatsApp. |
| As APIs de verificação de propriedade do telefone não estão disponíveis para esse caso de uso. | |
| Os webhooks não foram configurados para a conta de destino do WhatsApp Business. | Assine webhooks para seu app na conta do WhatsApp Business de destino. |
| Esse número de telefone pode ser adicionado diretamente e não requer o uso de APIs de migração de telefone. | |
| O número de telefone comercial deve ter um nome de exibição aprovado ( | O nome de exibição do seu número de telefone comercial precisa ser aprovado. |
| A conta do WhatsApp Business de origem e a opção "enviar mensagem em nome de" devem ser aprovadas. | A conta do WhatsApp Business pode estar usando o modelo de propriedade "Em nome de", que agora está obsoleto. Entre em contato com o suporte. |
| Sua conta do WhatsApp deve ter uma linha de crédito ativa para que você possa enviar mensagens após a migração. | |
| Ocorreu um erro ao migrar seu número de telefone. | Tente novamente mais tarde. Se isso não funcionar, entre em contato com o suporte. |
| As contas do WhatsApp Business de origem e destino devem representar a mesma empresa. | Migre o número de telefone para uma conta do WhatsApp Business que envia mensagens para a mesma empresa que a conta do WhatsApp Business de origem. |
| Para que você possa migrar números de telefone, a conta do WhatsApp Business de destino precisa ser aprovada. | Confira se a verificação da empresa foi concluída e se o status de análise da conta do WhatsApp Business está aprovado. |
| O cliente precisa aprovar o pedido "Mensagens para" da conta do WhatsApp Business de destino. | Peça ao cliente para aceitar seu pedido de "Mensagens para" no Meta Business Suite. |
| O número de telefone comercial está em modo de manutenção. | Tente novamente dentro de alguns minutos. |
Erros de insights sobre o modelo
Erro | Descrição | Solução possível |
| Os insights sobre o modelo ainda não estão disponíveis para esta conta do WhatsApp Business. | No momento, não é possível habilitar insights sobre o modelo para esta conta do WhatsApp Business. |
| Operação inválida. Depois de habilitados, os insights sobre o modelo não poderão ser desabilitados. | Depois de habilitados para uma conta do WhatsApp Business, os insights sobre o modelo não podem ser desabilitados. |
| Os insights sobre o modelo não foram habilitados para esta conta do WhatsApp Business | Para habilitar os insights sobre o modelo, consulte Como confirmar as análises de modelos. |
Erros de conta do WhatsApp Business
Erro | Descrição | Solução possível |
Insights sobre o modelo indisponíveis | Esta WABA já foi marcada para migração para uma identificação de solução diferente | O modelo de propriedade da conta OBO está obsoleto. Entre em contato com o suporte para obter ajuda. |
Conta do WhatsApp Business inválida para mobilidade OBO | A WABA não é qualificada para transferência de propriedade do tipo OBO. Os motivos possíveis são os seguintes:
| Informamos que o modelo de propriedade da conta OBO está obsoleto. Entre em contato com o suporte para obter ajuda. |
Erros de sincronização
Código | Detalhes | Possíveis motivos e soluções | Código de status HTTP |
Limite de pedidos de sincronização excedido | O número máximo de chamadas para a API de sincronização para este número de telefone foi excedido. | Só é possível chamar esse ponto de extremidade uma vez para sincronizar os contatos do número de telefone empresarial e uma vez para sincronizar o histórico de mensagens. Consulte Como integrar usuários do app de negócios. Desfaça a integração do cliente empresarial e depois refaça o processo de integração dele. |
Solicitação incorreta |
Pedido de sincronização feito fora do intervalo de tempo permitido | O pedido de sincronização só pode ser feito em até 24 horas depois da integração | Só é possível iniciar a sincronização dos contatos e do histórico de mensagens de um usuário integrado do app WhatsApp Business dentro de 24 horas depois da integração do usuário. Consulte Como integrar usuários do app de negócios. Desfaça a integração do usuário e depois refaça o processo de integração dele. |
Solicitação incorreta |
Erros de limitação
Código | Detalhes | Possíveis motivos e soluções | Código de status HTTP |
Quantidade excessiva de chamadas à API | O app atingiu o limite da taxa de chamadas de API. | Carregue o app no Painel de Apps e veja a seção Limite de volume do app para conferir se o limite de volume foi atingido. Em caso afirmativo, tente novamente mais tarde ou reduza a frequência ou a quantidade de consultas da API que o app está fazendo. |
Solicitação incorreta |
Problemas com limite de volume | A conta do WhatsApp Business atingiu o limite de volume. | Consulte os Limites de volume da conta do WhatsApp Business. Tente novamente mais tarde ou reduza a frequência ou a quantidade de consultas da API que o app está fazendo. |
Solicitação incorreta |
Limite de volume atingido | A taxa de transferência de dados de mensagens da API de Nuvem foi atingida. | O app atingiu o limite da taxa de transferência da API. Consulte Taxa de transferência de dados. Tente novamente mais tarde ou reduza a frequência com que o app envia mensagens. |
Solicitação incorreta |
Limite de taxa de spam atingido | Falha ao enviar a mensagem devido a um limite de envios que podem ser feitos deste número de telefone. É possível que muitas mensagens anteriores tenham sido bloqueadas ou marcadas como spam. | Verifique seu status de qualidade no Gerenciador do WhatsApp. Consulte Limites de modelo e Qualidade do modelo. |
Solicitação incorreta |
Limite de volume de emparelhamento atingido (conta comercial, conta de consumidor) | Foram enviadas muitas mensagens do número de telefone do remetente para o mesmo número de telefone do destinatário em um curto período. | Aguarde e realize novamente a operação se quiser enviar mensagens para o mesmo número de telefone. Você ainda pode enviar mensagens para um número diferente sem esperar |
Solicitação incorreta |
Limite de taxa de registro/exclusão de contas excedido | O registro ou a exclusão do registro falhou porque foram feitas muitas tentativas neste número de telefone em um curto período de tempo | O número de telefone comercial está sendo bloqueado porque atingiu o limite de tentativas de registro/cancelamento do registro. Tente novamente assim que o número for desbloqueado. Consulte a seção "Limitações" no documento Registro. |
|
Outros erros
Código | Detalhes | Possíveis motivos e soluções | Código de status HTTP |
API desconhecida | Pedido inválido ou possível erro do servidor. | Consulte a página Status da API do WhatsApp Business para ver as informações de status da API. Se não houver interrupções no servidor, consulte a referência do ponto de extremidade para verificar se o pedido está formatado corretamente e cumpre todos os requisitos necessários. |
Solicitação incorreta |
Serviço de API | Há um erro temporário por inatividade ou sobrecarga. | Antes de tentar de novo, consulte a página Status da API do WhatsApp Business para ver as informações de status da API. |
Serviço indisponível |
Valor do parâmetro não é válido | O número de telefone comercial foi excluído. | Verifique se o número de telefone comercial está correto. |
Solicitação incorreta |
Parâmetro inválido | O pedido incluía um ou mais parâmetros incompatíveis ou escritos de forma errada. | Consulte a referência do ponto de extremidade para determinar quais parâmetros são compatíveis e como são escritos. Para o WhatsApp Flows com ponto de extremidade: ao configurar a chave pública da empresa, verifique se ela é uma chave RSA pública e válida de 2.048 bits no formato PEM. Verifique se não há incompatibilidade entre o ID do número de telefone que você está registrando e outro armazenado anteriormente. Verifique se o parâmetro está dentro de qualquer restrição de tamanho para o tipo. |
Solicitação incorreta |
O número do usuário faz parte de um experimento | A mensagem não foi enviada como parte de um experimento. | Consulte Experimento de mensagem de marketing. |
Solicitação incorreta |
Ocorreu um erro | Falha ao enviar a mensagem devido a um erro desconhecido. | Tente novamente. Se o erro persistir, abra um tíquete de Suporte Direto. Para o WhatsApp Flows com ponto de extremidade: durante a definição da chave pública da empresa, ocorreu uma falha ao calcular a assinatura, fazer uma chamada ao ponto de extremidade do GraphQL ou o ponto de extremidade do GraphQL retornou um erro. |
Erro interno do servidor |
Acesso negado | A permissão não foi concedida ou foi removida. | Use o depurador de token de acesso para verificar se as permissões necessárias foram concedidas ao seu app pelo ponto de extremidade. Consulte Erros de autenticação e autorização. |
Proibido |
O parâmetro obrigatório está ausente | Falta um parâmetro obrigatório no pedido. | Consulte a referência do ponto de extremidade para determinar quais parâmetros são necessários. |
Solicitação incorreta |
Valor do parâmetro não é válido | Um ou mais valores de parâmetros são inválidos. | Consulte a referência do ponto de extremidade para determinar quais valores são compatíveis com cada parâmetro. Confira a documentação Números de telefone para saber como adicionar um número a uma conta do WhatsApp Business. |
Solicitação incorreta |
Serviço indisponível | Um serviço está temporariamente indisponível. | Antes de tentar de novo, consulte a página Status da API do WhatsApp Business para ver as informações de status da API. |
Erro interno do servidor |
O destinatário não pode ser o remetente | O número de telefone do destinatário e do remetente é o mesmo. | Envie uma mensagem para um número de telefone diferente daquele do remetente. |
Solicitação incorreta |
A mensagem não pode ser entregue | Não foi possível entregar a mensagem. Os motivos podem ser os seguintes:
| Usando um método de comunicação diferente do WhatsApp, peça ao usuário do WhatsApp para fazer o seguinte:
|
Solicitação incorreta |
O nome de exibição do número fornecido pelo WhatsApp precisa ser aprovado antes que a mensagem possa ser enviada. | O número de telefone comercial 555 usado para enviar o pedido não tem um nome de exibição aprovado. | Altere o nome de exibição do número de telefone comercial 555. Consulte também o artigo da Central de Ajuda Como alterar o nome de exibição no WhatsApp Business. |
Solicitação incorreta |
Qualificação da empresa – problema com o pagamento | Ocorreu um erro relacionado à forma de pagamento. | Consulte Sobre a cobrança da sua conta do WhatsApp Business e verifique se a cobrança foi configurada corretamente. Problemas comuns:
|
Solicitação incorreta |
Certificado incorreto | Ocorreu uma falha ao enviar a mensagem devido a um erro de registro do número de telefone. | Registre o número de telefone e tente novamente. |
Erro interno do servidor |
Mensagem de reengajamento | Mais de 24 horas se passaram desde que o destinatário respondeu pela última vez ao número do remetente. | Envie um modelo de mensagem ao destinatário. |
Solicitação incorreta |
A Meta escolheu não entregar a mensagem. | Essa mensagem não foi entregue para manter o engajamento saudável do ecossistema. | Se você receber esse código de erro e suspeitar que seja devido ao limite, espere pelo menos 24 horas antes de reenviar a mensagem de modelo. Fazer isso só resultará em outra resposta de erro, já que o limite pode estar em vigor em diferentes períodos. Consulte Limites de mensagem de modelo de marketing por usuário para mais informações. |
Solicitação incorreta |
O usuário não recebe mais mensagens de marketing. | Não é possível entregar a mensagem. O destinatário interrompeu o recebimento de mensagens de marketing da sua empresa no WhatsApp. | Não tente enviar mensagens novamente, já que elas não serão recebidas por este usuário. Para receber uma notificação sempre que um usuário do WhatsApp interromper ou retomar o recebimento de mensagens de modelo de marketing da sua empresa, assine o webhook user_preferences. |
Solicitação incorreta |
Tipo de mensagem não compatível | O tipo de mensagem não é compatível. | Consulte Mensagens para ver os tipos de mensagem compatíveis antes de tentar novamente. |
Solicitação incorreta |
Erro de download de mídia | Não foi possível baixar a mídia enviada pelo usuário. | Não foi possível baixar mídias incluídas na mensagem do usuário do WhatsApp. Para saber mais, consulte o valor Peça ao usuário do WhatsApp para enviar o arquivo de mídia usando um método que não seja o WhatsApp. |
Solicitação incorreta |
Erro de carregamento de mídia | Não foi possível carregar a mídia usada na mensagem. | Não foi possível carregar a mídia por um ou mais motivos, por exemplo, um tipo de mídia não compatível. Para saber mais, consulte o valor Recomendamos que você inspecione os arquivos de mídia que estão causando erros e confirme se eles são realmente compatíveis. Por exemplo, no UNIX, é possível usar a inspeção de arquivos por meio da linha de comando para determinar o tipo MIME:
Você pode então confirmar se o seu tipo MIME é compatível. Consulte Tipos de mídia compatíveis. |
Solicitação incorreta |
Conta em modo de manutenção | A conta comercial está em modo de manutenção | A conta do WhatsApp Business está em modo de manutenção. Talvez a conta esteja passando por uma atualização da taxa de transferência de dados. |
Solicitação incorreta |
Incompatibilidade na contagem de parâmetros do modelo | O número de valores de parâmetros variáveis incluídos no pedido não corresponde ao número de parâmetros variáveis definidos no modelo. | Consulte o documento Modelos para saber mais sobre parâmetros e garantir que o pedido inclua valores para todos os parâmetros exigidos pelo modelo. |
Solicitação incorreta |
Modelo não existe | O modelo não existe no idioma especificado ou não foi aprovado. | Verifique se o modelo foi aprovado e se o nome e a localidade do idioma estão corretos. Consulte o documento Modelos para saber mais sobre modelos. |
Não encontrado |
Texto hidratado do modelo longo demais | O texto traduzido é longo demais. | Consulte o Gerenciador do WhatsApp para verificar se o seu modelo foi traduzido. Consulte o documento Qualidade do modelo para saber como verificar o status do seu modelo. |
Solicitação incorreta |
Política de caracteres do formato do modelo violada | O conteúdo do modelo viola uma política do WhatsApp. | Para saber mais sobre os possíveis motivos de violação, consulte o documento Análise do modelo. |
Solicitação incorreta |
Incompatibilidade no formato do parâmetro do modelo | Os valores de parâmetros variáveis foram formatados incorretamente. | Os valores de parâmetros variáveis incluídos no pedido não estão usando o formato especificado no modelo. Consulte o documento Modelos para saber mais sobre parâmetros e formatos de modelos. |
Solicitação incorreta |
Modelo pausado | O modelo foi pausado por baixa qualidade e não pode ser enviado em mensagens. | Edite o modelo para melhorar a qualidade e tente novamente após a aprovação. |
Solicitação incorreta |
Modelo desabilitado | O modelo foi pausado muitas vezes por baixa qualidade e foi desabilitado de forma permanente. | Crie um modelo novo com conteúdo diferente. |
Solicitação incorreta |
O flow está bloqueado | O flow está no estado bloqueado. | Corrija o flow |
Solicitação incorreta |
O flow é limitado | O flow está no estado limitado e 10 mensagens usando esse flow já foram enviadas na última hora. | Corrija o flow |
Solicitação incorreta |
Cancelamento do registro incompleto | Uma tentativa anterior de cancelamento do registro falhou. | Exclua o registro do número novamente antes de registrá-lo. |
Erro interno do servidor |
Servidor temporariamente indisponível | O servidor está temporariamente indisponível. | Antes de tentar novamente, consulte a página Status da plataforma do WhatsApp Business para ver as informações de status da API e verifique o valor da resposta |
Serviço indisponível |
Incompatibilidade do PIN na confirmação em duas etapas | O PIN de confirmação em duas etapas está incorreto. | Verifique se o PIN incluído no pedido está correto. Para redefinir o PIN, desative a confirmação em duas etapas e defina um novo PIN. Veja Confirmação em duas etapas. |
Solicitação incorreta |
É necessária uma nova verificação do número de telefone | O número de telefone precisa ser verificado antes do registro. |
Solicitação incorreta | |
Muitas tentativas do PIN de confirmação em duas etapas | Ocorreram muitas tentativas do PIN de confirmação em duas etapas para este número de telefone. | Tente novamente após o período especificado no valor de resposta |
Solicitação incorreta |
Tentativa muito rápida do PIN de confirmação em duas etapas | O PIN de confirmação em duas etapas foi inserido muito rapidamente. | Consulte o valor da resposta |
Solicitação incorreta |
Número de telefone não registrado | O número de telefone não está registrado na Plataforma do WhatsApp Business. | Registre o número de telefone e tente novamente. |
Solicitação incorreta |
Aguarde alguns minutos antes de tentar registrar o número de telefone | O número de telefone que você está tentando registrar foi excluído recentemente e a exclusão ainda não foi concluída. | Espere 5 minutos antes de tentar novamente. |
Solicitação incorreta |
Os Termos de Serviço do Pagamentos no WhatsApp não foram aceitos | O envio da mensagem falhou porque a aceitação dos Termos de Serviço do Pagamentos no WhatsApp por esta conta do WhatsApp Business está pendente. | Aceite os Termos de Serviço do Pagamentos no WhatsApp usando o link fornecido na mensagem de erro antes de tentar novamente. |
Solicitação incorreta |
Erro genérico do usuário | Falha ao enviar a mensagem devido a um erro desconhecido com seus parâmetros de pedido. | Consulte a referência do ponto de extremidade para determinar se a consulta ao ponto de extremidade está sendo feita com a sintaxe correta. Entre em contato com o suporte ao cliente se continuar a receber esse erro na resposta. |
Solicitação incorreta |