Muito longo? Leia isto primeiro ● Os erros da API do WhatsApp Business quase sempre caem em cinco tipos: configuração da conta, templates, entrega, limites de envio ou integração. Identifique o tipo primeiro, depois confira o código. ● O erro 131047 significa que a janela de atendimento de 24 horas fechou. Envie um template aprovado no lugar de uma mensagem comum. ● Rejeições de template acontecem, na maioria das vezes, porque a categoria escolhida estava errada. Conteúdo de marketing enviado como Utilidade tende a ser rejeitado. ● Uma classificação de qualidade vermelha não gera banimento imediato, mas pausa templates e trava o aumento do limite de mensagens. ● Os erros 131048 e 130429 geralmente significam que você está enviando rápido demais. Reduza o ritmo, tente de novo após um intervalo e melhore sua lista de opt-in. |
Sua campanha de Black Friday está agendada. 40.000 contatos, template aprovado, tudo na fila.
Você clica em enviar e o painel fica vermelho. 131047. 132001. 131048.
Nenhuma explicação em português claro, só uma parede de códigos de cinco dígitos e uma campanha que não sai do lugar.
Se você já opera a API do WhatsApp Business, o canal oficial da Meta para falar com clientes em escala, há mais de algumas semanas, já encontrou esses códigos. Como a Meta controla o pipeline inteiro, toda falha volta como um número.
O canal é valioso demais para você perder uma campanha por causa de um código que não reconhece:
- Mais de 3 bilhões de pessoas no WhatsApp
- Taxas de abertura chegando a 98%
A boa notícia: os erros da API do WhatsApp são bem mais previsíveis do que parecem.
- Quase todo erro tem origem em cinco causas raiz
- A maioria leva menos de 10 minutos para resolver, desde que você saiba em qual grupo está
Este guia cobre todos os códigos de erro que você provavelmente vai encontrar, o que realmente causa cada um e exatamente como corrigir.
O que são erros da API do WhatsApp Business?
Um erro da API do WhatsApp Business é uma resposta codificada que a Meta devolve quando uma solicitação sua (enviar uma mensagem, submeter um template, registrar um número) não pode ser concluída.
Diferente do aplicativo WhatsApp Business, em que uma mensagem falha apenas exibe o ícone de relógio, a API informa com precisão o que deu errado. Isso é um recurso, não um defeito. O problema é que as mensagens de erro da Meta são escritas para desenvolvedores, e não para profissionais de marketing. Por isso "Re-engagement message" não deixa óbvio que "sua janela de 24 horas expirou".
Todo erro que você vai encontrar pertence a um destes cinco grupos:
- Erros de conta e configuração: seu número, WABA ou verificação do negócio não está em um estado que permita envio
- Erros de template: o template não existe, foi rejeitado, foi pausado ou suas variáveis não batem
- Erros de entrega: a mensagem era válida, mas não conseguiu chegar àquele destinatário específico
- Erros de limite de envio: você está enviando mais rápido ou mais volume do que sua conta permite no momento
- Erros de integração: seu token, webhook ou ferramenta conectada quebrou a cadeia
Saber o grupo já resolve uns 80% do caminho até a solução. O código resolve o resto.
Como ler uma resposta de erro da API do WhatsApp
Toda solicitação com falha retorna um objeto JSON parecido com este:
{
"error": {
"message": "(#131047) Re-engagement message",
"type": "OAuthException",
"code": 131047,
"error_data": {
"messaging_product": "whatsapp",
"details": "Message failed to send because more than 24 hours have passed since the customer last replied to this number."
},
"fbtrace_id": "AbCdEfGhIjK"
}
}Quatro nomenclaturas que você precisa saber:
- code: o número de cinco dígitos. É o que você pesquisa e o que organiza tudo o que vem abaixo.
- message: o título curto da Meta. Costuma ser críptico ("Re-engagement message" sozinho não diz quase nada).
- error_data.details: a explicação de verdade, em texto corrido. A maioria das pessoas pula direto para o código e perde esse campo, que normalmente nomeia o problema exato.
- fbtrace_id: um ID único daquela solicitação específica. Sempre inclua isso ao abrir um chamado de suporte. Sem ele, a Meta não consegue rastrear o que aconteceu.
Onde conferir os erros:
- Na AiSensy: abra a campanha e vá em Delivery Logs (registros de entrega). Você vê o código de erro de cada contato que falhou.
- Na Meta: abra o WhatsApp Manager para verificar qualidade dos templates, problemas na conta ou restrições no número de telefone.
Observação importante: se o mesmo erro aparece para todo mundo, o problema provavelmente está na conta ou no template enviado.
Se apenas alguns contatos são afetados, é mais provável que seja um problema de entrega.
Leia mais: Qual a melhor ferramenta de disparo em massa no WhatsApp
Códigos de Erro da API do WhatsApp Business: Tabela de Referência Completa
Aqui está a lista completa dos códigos que você realmente vai encontrar, agrupados por tipo. Salve esta seção nos favoritos, é o caminho mais rápido do código até a causa.
Erros de Autorização e de Permissão
Estes são erros de token ou credencial que o BSP (provedor de soluções do WhatsApp) resolve pelo usuário. Um profissional de marketing na sua plataforma nunca encosta neles.
Esses erros são gerenciados pelo seu BSP (como a AiSensy), então acione o suporte caso apareçam.
| Código | Erro | O que significa | Solução |
|---|---|---|---|
| 0 | Falha na autenticação | Token expirado, invalidado ou acesso revogado | Gere um novo token de acesso |
| 3 | Problema de capacidade ou permissão | O token não tem a permissão necessária | Verifique as permissões no Access Token Debugger da Meta |
| 10 | Permissão negada | A permissão nunca foi concedida ou foi removida | Autorize o app novamente no Business Manager |
| 190 | Token de acesso expirado | Sua autorização na Meta caducou | Reconecte via Embedded Signup |
| 200 | Falha de autorização | Token inválido ou escopo de permissão ausente | Reautorize com os escopos corretos |
| 131005 | Permissão não concedida | O token não pertence a esta WABA ou a este número | Confirme se o token aponta para o negócio certo |
Erros de Throttling e Limite de Envio
Este erro significa que você está enviando rápido demais, ou volume demais para o seu tier atual.
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 4 | API rate limit reached | Your app hit its call rate ceiling | Back off, retry with exponential delay |
| 80007 | WABA rate limit | The WhatsApp Business Account hit its limit | Reduce request frequency |
| 130429 | Throughput limit | Cloud API message throughput exceeded (~80 msg/sec) | Queue messages and retry with backoff |
| 131048 | Spam rate limit | Too many of your recent messages were blocked or reported | Pause, clean your list, improve template quality |
| 131056 | Pair rate limit | Too many messages to the same recipient too quickly | Add per-recipient delay |
| 131064 | Classification limit | Messaging restricted due to template category violations | Re-check and correct template categories |
| 133016 | Too many registration attempts | Number registration retried excessively | Wait for the cooldown to lift |
Erros de Envio e Entrega de Mensagens
A solicitação era válida, mas a mensagem não chegou ao destinatário.
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 131026 | Message undeliverable | Recipient isn't on WhatsApp, has an outdated app, or can't receive it | Validate the number and opt-in status |
| 131047 | Re-engagement required | 24+ hours since the customer last replied | Send an approved template instead |
| 131049 | Marketing limit reached | Per-user marketing message cap hit | Wait 24 hours before resending |
| 131050 | Marketing opt-out | User has stopped marketing messages from you | Suppress from all marketing sends |
| 131051 | Unsupported message type | Message structure is wrong for the type declared | Fix the message object structure |
| 131052 | Media download failed | Couldn't download the user's media | Ask the user to resend |
| 131053 | Media upload failed | Your media couldn't be uploaded | Verify MIME type, size and URL |
| 130403 | User blocked by business | You've blocked this user | Unblock to resume sending |
Template Errors
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 132000 | Variable count mismatch | Number of variables sent ≠ number in the approved template | Match the variable count exactly |
| 132001 | Template not found | Template name or language doesn't exist / isn't approved | Check exact name, language code and approval status |
| 132005 | Translated text too long | Variable values pushed the template past its limit | Shorten your variable values |
| 132007 | Policy violation | Template content violates WhatsApp policy | Rewrite per Template Review guidelines |
| 132012 | Parameter format mismatch | Parameter values formatted incorrectly | Match component and button parameter formats |
| 132015 | Template paused | Low quality caused a temporary pause | Improve quality or switch templates |
| 132016 | Template disabled | Paused too many times, now permanently off | Create a new template with different content |
| 2388019 | Template limit exceeded | WABA is at its 250-template ceiling | Delete unused templates |
Na Cloud API, que praticamente todas as empresas usam hoje, os equivalentes são 131047 e 131026, respectivamente.
Erros de Onboarding e Configuração de conta
Estes travam você antes mesmo do primeiro envio. (Se você ainda não começou sua solicitação, siga primeiro nosso guia passo a passo da API do WhatsApp Business. Vários desses erros só fazem sentido quando você sabe em que ponto do fluxo está.)
Erro "número já registrado"
Costuma acontecer quando o número já está ativo no WhatsApp ou no aplicativo WhatsApp Business.
Um número de telefone só pode estar conectado a um produto WhatsApp por vez, então você precisa removê-lo ou migrá-lo antes de registrá-lo na API.
Códigos relacionados que podem aparecer nesse processo:
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 133000 | Deregistration incomplete | A previous deregistration didn't complete | Deregister again, then retry |
| 133010 | Number not registered | The number isn't registered on the platform yet | Complete registration before attempting to send |
| 133006 | Number not verified | The number hasn't been verified | Finish OTP verification first |
| 2388012 | Number already exists | The number already exists in the target WhatsApp account during a migration | Remove it from the target account, then retry the migration |
Importante: se o número está em um chip que você ainda usa no WhatsApp pessoal, não faça isso.
Use um número novo para a API. Depois que um número entra na API, você não consegue mais usá-lo no aplicativo WhatsApp do seu celular.
Verificação do Negócio e Rejeição do Nome de Exibição
São duas checagens diferentes quando o assunto é verificação do negócio e rejeição do nome de exibição.
Verificação do Negócio
A Meta confere se sua empresa está legalmente registrada. A verificação pode falhar quando os dados do Business Manager não batem exatamente com os documentos.
Por exemplo, "Têxtil Souza Comércio Ltda." e "Têxtil Souza" podem ser tratados como nomes diferentes.
Como corrigir:
- Deixe a razão social idêntica à dos documentos.
- Envie um documento que mostre nome da empresa, endereço e CNPJ.
- Garanta que seu site exiba os mesmos dados da empresa.
- Se for rejeitado duas vezes, fale com o Suporte da Meta em vez de reenviar o mesmo documento.
Rejeição do Nome de Exibição
O nome de exibição é o nome que os clientes veem no WhatsApp.
A Meta pode rejeitar nomes que:
- Não correspondem à sua empresa ou marca
- São genéricos demais, como "Melhores Ofertas"
- Incluem URLs, telefones, emojis ou ofertas
- Usam uma marca registrada cuja titularidade você não consegue comprovar
A opção mais segura é a razão social registrada ou um nome de marca claramente ligado ao seu site.
Erro relacionado:
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 131037 | Display name not approved | Your test number doesn't have an approved display name yet | Submit a compliant display name and wait for approval before sending |
Erros de Template de Mensagem do WhatsApp
Erros de template podem travar uma campanha inteira, o que os torna um dos problemas mais comuns da API do WhatsApp.
Por que a Meta rejeita templates
A maioria das rejeições acontece porque a categoria escolhida estava errada.
Qualquer mensagem com conteúdo promocional é tratada como Template de Marketing. Por exemplo, uma atualização de entrega que divulga produtos novos pode ser rejeitada se for enviada como template de utilidade.
Estes são os motivos mais comuns de rejeição:
| Rejection Reason | What Triggers It | How to Fix |
|---|---|---|
| Incorrect category | Promotional content submitted as UTILITY or AUTHENTICATION | Resubmit under MARKETING; keep utility templates purely transactional |
| Variable parameter issues | Template starts or ends with {{1}}, or has two variables adjacent | Always wrap variables in static text - Hi {{1}}, your order is confirmed |
| Too many variables for the length | Variable-to-text ratio too high | Add more static copy, or reduce variable count |
| Placeholder content | Sample values left as {{1}} or "lorem ipsum" | Provide realistic sample values for every variable |
| Policy violation (132007) | Prohibited industry, misleading claims, or restricted goods | Rewrite to remove the prohibited element; check Meta's Commerce Policy |
| Formatting errors (2388040, 2388047, 2388072) | Field exceeds character limit, or header/body/footer malformed | Body max 1,024 characters, header 60, footer 60 |
| Abusive or threatening tone | Aggressive debt-collection or pressure language | Neutral, factual phrasing |
| Broken link or mismatched URL | URL in the button doesn't resolve, or doesn't match your business | Use live URLs on your verified domain |
Três dicas práticas que melhoram bastante a taxa de aprovação:
- Não comece a mensagem com uma variável. Escreva "Olá {{1}}" em vez de abrir direto com "{{1}}".
- Coloque valores de amostra de verdade. A Meta revisa a prévia final da mensagem, não só o formato do template.
- Envie os templates com antecedência. Em períodos de pico, a aprovação demora mais, então submeta pelo menos 48 horas antes da campanha.
Templates Pausados, Desativados ou Sinalizados
Um template aprovado não fica aprovado para sempre. A Meta pontua continuamente cada template com base na reação dos destinatários.
132015, template pausado. A qualidade do seu template caiu para baixa, normalmente por taxa de bloqueio e denúncia. A pausa é temporária:
- Primeira pausa: 3 horas
- Segunda pausa: 6 horas
- Terceira pausa: 24 horas
Templates pausados voltam sozinhos. Use o período de pausa para melhorar a qualidade da lista de inscritos e reduzir a frequência de envio.
O erro 132016 significa que o template foi desativado em definitivo. Crie um novo template com conteúdo diferente.
Para evitar isso:
- Envie apenas para opt-ins recentes
- Limite a frequência de marketing
- Segmente seu público
- Monitore a qualidade dos templates toda semana
Correções rápidas de template
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 132000 | Variable count mismatch | You sent 3 variables to a template expecting 2 (or vice versa) | Count them again, including button and header variables |
| 132001 | Template not found | Usually the language code - a template approved as en_US won't send if you call en | Check the exact language code, not just the name |
| 132005 | Translated text too long | Variable values pushed the rendered message past the character limit | Truncate long values (product names, addresses) before injecting them |
| 132012 | Parameter format mismatch | Component or button parameters don't match the approved structure - commonly a URL button variable passed in the body array | Match parameters to the approved component structure |
| 2388293 | Parameter ratio exceeds limit | Too many variables relative to static text | Add copy or cut variables |
| 2388019 | Template limit exceeded | You're at the 250-template ceiling | Delete unused templates |
Se você ainda está definindo qual formato usar em cada situação, vale conferir os tipos de mensagens template do WhatsApp e a biblioteca de templates prontos.
Erros de Entrega de Mensagens no WhatsApp
Estes aparecem quando a mensagem em si está certa, mas o destinatário ou o contexto não está.
Erro 131047: Mensagem de Reengajamento Necessária
O erro 131047 significa que a janela de atendimento de 24 horas fechou.
A janela abre quando um cliente manda mensagem para você. Durante essas 24 horas, você pode enviar respostas comuns, imagens ou documentos.
Depois que a janela fecha, só templates aprovados podem ser enviados.
Como corrigir:
- Verifique quando o cliente mandou mensagem pela última vez
- Se a janela estiver fechada, envie um template aprovado
- Assim que o cliente responder, a janela de 24 horas abre de novo
Como evitar:
- Confira o cronômetro da janela antes de responder
- Crie templates para follow-ups com prazo curto
- Use lembretes automáticos antes de a janela fechar
Erros relacionados:
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 131049 | Marketing limit reached | The user has hit Meta's per-user marketing message cap for that time window | Wait 24 hours before resending; segment to engaged users and space out marketing sends |
| 131050 | Marketing opt-out | The user has opted out of marketing messages from you | Suppress from all marketing sends until they opt back in on their device |
No Brasil, o opt-out normalmente chega como uma resposta SAIR, então garanta que sua base trate essa palavra como pedido de descadastro imediato.
Erro 131026: Mensagem não Entregável
Isso significa que o WhatsApp aceitou a mensagem, mas não conseguiu entregar a mensagem.
Motivos comuns:
- O número não está ativo no WhatsApp
- O código do país ou o formato do número está incorreto
- O destinatário usa uma versão desatualizada do WhatsApp
- O aparelho dele não suporta aquele tipo de mensagem
- A conta está restrita
- O envio de mensagens é limitado naquela região
Como corrigir:
- Use o formato internacional completo, sem [+], espaços ou zeros à esquerda
- Valide os números antes de subir a lista de contatos
- Remova números que falham de forma recorrente
- Se muitos contatos apresentam esse erro, confira primeiro a formatação da sua lista
Um número brasileiro deve ficar assim: 5511987654321.
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 131051 | Unsupported message type | Your message object doesn't match the type you declared - usually a malformed interactive or media payload | Fix the message object structure to match the declared type |
| 130403 | User blocked by business | You blocked them at some point | Unblock in Live Chat to resume |
| 131031 | Account locked | Account-level restriction or a failed verification check | Check account health before retrying anything |
Limites de Envio e Limites de Mensagens
São controles de vazão, não punições. Existem para impedir que uma conta comprometida ou mal configurada inunde os usuários.
Tiers de mensagens do WhatsApp explicados
Toda conta do WhatsApp Business fica em um tier de mensagens que limita quantos clientes únicos você pode iniciar conversa a cada 24 horas corridas. Respostas a clientes que falaram com você primeiro não entram nessa conta.
| Tier | Unique customers per 24 hours | How you get there |
|---|---|---|
| Tier 0 | 250 | Default for every new business portfolio |
| Tier 1 | 2,000 | Complete Business Verification, or send 2,000 quality messages to unique users in 30 days |
| Tier 2 | 10,000 | Automatic scaling |
| Tier 3 | 100,000 | Automatic scaling |
| Tier 4 | Unlimited | Automatic scaling |
Duas atualizações importantes:
- Os limites de mensagens agora valem no nível do Portfólio de Negócios, então todos os números conectados compartilham o tier mais alto disponível.
- A Meta revisa os aumentos de tier a cada poucas horas, então contas elegíveis podem subir no mesmo dia.
Como Aumentar seu Limite de Mensagens
A Meta costuma aumentar seu limite quando:
- Você usa pelo menos 50% do limite atual em 7 dias
- A qualidade da sua conta e dos seus templates se mantém alta
Veja também como planejar disparos em massa sem estourar seus limites.
Para melhorar suas chances:
- Conclua a Verificação do Negócio
- Use o limite disponível de forma consistente
- Mantenha sua classificação de qualidade verde
- Aumente o volume de mensagens de forma gradual
- Mantenha um uso estável ao longo dos 7 dias
Escolher o melhor horário para enviar seus disparos ajuda a manter o engajamento alto enquanto você sobe de tier.
Códigos de Erro de Limite de Envio
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 131048 | Spam rate limit | The serious one - too many of your recent messages were blocked or reported, so Meta throttled you | Stop sending immediately, audit which template or segment drove the blocks, and resume at lower volume |
| 130429 | Cloud API throughput limit | You exceeded roughly 80 messages per second | Queue and retry with exponential backoff - any competent BSP handles this for you automatically |
| 4 / 80007 | API call rate limit | Your app or WABA is making too many API calls | Reduce polling frequency |
| 131056 | Pair rate limit | Too many messages to the same recipient too quickly | Add a per-recipient delay |
| 131064 | Classification limit | Restricted because of repeated template category violations | Audit your template categories |
| 132069 | Flow throttled | More than 10 flow messages sent in an hour to a recipient | Slow down |
Classificação de Qualidade e Restrições de Conta
A classificação de qualidade é a métrica que, silenciosamente, determina todo o resto: seu tier, se os templates continuam ativos e se o seu número sobrevive.
Qualidade verde, amarela e vermelha explicada
A Meta pontua cada número de telefone pela reação dos destinatários às suas mensagens em uma janela corrida de 7 dias.
Bloqueios e denúncias derrubam a nota. Engajamento e respostas sustentam.
| Rating | What it means | What happens | What to do |
|---|---|---|---|
| Green (High) | Healthy engagement, minimal blocks | Full scaling eligibility | Maintain current practice |
| Yellow (Medium) | Blocks or reports rising | Tier upgrades freeze; you're being watched | Pause marketing, audit lists, cut frequency |
| Red (Low) | Significant negative feedback | Advancement blocked, templates start pausing | Stop all promotional sending for 7 days |
Uma classificação vermelha não causa rebaixamento imediato, mas se persistir, templates podem ser desativados e o número pode ser restringido.
Causas comuns:
- Enviar para usuários sem opt-in claro
- Enviar para listas antigas ou inativas
- Disparar promoções com frequência excessiva
- Enviar mensagens irrelevantes em massa
- Enviar conteúdo que o usuário não pediu para receber
A qualidade depende muito mais da reação do usuário do que do volume de mensagens. Mensagens relevantes para uma base com opt-in mantêm sua nota saudável, enquanto uma segmentação ruim leva a nota para o vermelho rapidamente. Se o assunto é conformidade, vale entender como uma crise de conformidade no WhatsApp Business se instala.
O que Fazer se seu Número for Restringido
Os erros 368 ou 131031 significam que o WhatsApp interrompeu os envios da sua conta. Veja como desbanir seu número do WhatsApp Business.
O que fazer:
- Confira o aviso de restrição no Business Manager
- Pare de enviar mensagens daquele número
- Revise o motivo exato no painel do seu BSP
- Envie um recurso pelo WhatsApp Manager
- Explique o que aconteceu e o que você mudou
- Anexe provas, como formulários de opt-in ou uma lista de contatos higienizada
Evite recursos genéricos do tipo "por favor, restaure minha conta". Provas claras aumentam suas chances.
Não crie um número novo para continuar a mesma prática. A Meta pode restringir esse número também.
Sinais de Alerta
Fique de olho em:
- Queda nas taxas de entrega
- Qualidade saindo do verde para o amarelo
- Templates sendo pausados
- Taxas de leitura caindo
- Aumentos de tier esperados que não acontecem
Corrija a qualidade da lista e a frequência de envio antes de a restrição piorar.
Erros de Mídia e de Anexos
Erros de mídia normalmente acontecem porque o arquivo é grande demais, não é suportado ou está inacessível.
Problemas comuns:
- O arquivo ultrapassa o limite de tamanho do WhatsApp
- O formato ou o tipo real do arquivo não é suportado
- A URL da mídia é privada, está quebrada ou não é HTTPS
- O media ID enviado expirou
Erros relacionados:
| Code | Error | What It Means | Fix |
|---|---|---|---|
| 131053 | Media upload failed | Your media couldn't be uploaded, often due to a file type mismatch | Verify the MIME type, size, and URL, then re-upload |
| 131052 | Media download failed | WhatsApp couldn't download the media | Ask the user to resend it |
Para arquivos usados com frequência, suba a mídia uma vez e reaproveite o media ID em vez de depender de links externos.
Erros da API do WhatsApp: Dicas Rápidas de Diagnóstico
Quando uma mensagem falhar, confira estes pontos nesta ordem:
- Leia os detalhes completos do erro, não só o código
- Veja se o erro afeta todos os contatos ou apenas alguns
- Verifique se sua conta está restrita
- Revise sua classificação de qualidade
- Confirme nome, idioma, status e variáveis do template
- Cheque se a janela de 24 horas está aberta
- Valide o formato do número do destinatário
- Verifique seu token de acesso e a configuração do webhook
Ainda travado?
Salve o fbtrace_id, o horário e a resposta de erro completa antes de acionar o suporte.
Como a AiSensy Ajuda a Evitar Erros da API do WhatsApp
A AiSensy ajuda a prevenir os problemas mais comuns da API do WhatsApp antes que eles atinjam suas campanhas.
- Verifica templates antes do envio para aprovação
- Avisa quando a qualidade cai
- Mostra erros de entrega de forma clara
- Cuida das novas tentativas e dos limites de envio
- Exibe o cronômetro da janela de 24 horas
- Apoia a verificação e a configuração da conta
Explore todos os recursos da plataforma, veja casos de uso reais ou confira os estudos de caso.
Comece grátis e configure sua API do WhatsApp Business com menos erros.
Conclusão
Os erros da API do WhatsApp parecem técnicos, mas a maioria fica simples assim que você entende o que cada código quer dizer.
Para evitar problemas recorrentes, foque em quatro coisas: colete opt-ins de verdade, segmente seu público, não exagere na frequência e monitore sua classificação de qualidade.
Faça isso de forma consistente e os erros da API do WhatsApp passam a ser exceção, não rotina.
Perguntas frequentes
Significa que a janela de atendimento de 24 horas fechou, ou seja, passaram mais de 24 horas desde a última mensagem daquele cliente. Você não pode mais enviar mensagens livres. Envie um template aprovado e, assim que ele responder, a janela reabre.
O motivo mais comum é categoria incorreta, com conteúdo promocional enviado como UTILITY. Outras causas frequentes são templates que começam ou terminam com variável, valores de amostra ausentes, variáveis coladas sem texto entre elas e URLs quebradas nos botões. Confira o motivo da rejeição no WhatsApp Manager, corrija aquele ponto específico e reenvie.
O erro 131026 normalmente significa que o número não está no WhatsApp ou está formatado de forma errada. Confira se os números estão em formato internacional completo, sem +, espaços ou zeros à esquerda. Um número brasileiro deve ficar 5511987654321. Se uma fatia grande da campanha falha assim, o problema é a formatação da lista.
Restrições (368, 131031) vêm de violações de política, classificação de qualidade baixa por período prolongado ou falha na verificação do negócio. O motivo exato aparece no aviso de restrição do seu Business Manager. Pare de enviar, leia o aviso, corrija a causa e recorra com evidências do que você mudou.
No Meta Business Manager, vá em WhatsApp Manager → Números de Telefone, onde cada número exibe uma nota verde, amarela ou vermelha. Na AiSensy ela aparece no seu painel, junto com alertas quando muda.
É o erro 131047. O WhatsApp abre uma janela de 24 horas quando um cliente manda mensagem para você, e nesse período você pode responder livremente. Depois que fecha, só templates pré-aprovados são permitidos.
Conclua a Verificação do Negócio para sair de 250 e chegar a 2.000. Acima disso, a Meta aumenta automaticamente quando você usa pelo menos 50% do limite atual ao longo de 7 dias e sua classificação de qualidade está alta. A Meta avalia a cada 6 horas.
Confira nesta ordem: sua conta está restrita, sua classificação de qualidade está vermelha, o template está aprovado e referenciado corretamente, os números estão formatados certo e você atingiu seu limite de mensagens. O código de erro de cada mensagem com falha reduz a busca na hora.
Sim. Pare todo envio promocional por cerca de 7 dias, mantenha apenas conversas iniciadas pelo cliente, audite sua lista de opt-in e retome aos poucos com envios bem segmentados. As notas são calculadas em janela corrida, então os sinais negativos antigos vão saindo da conta.
O destinatário não está no WhatsApp, o número dele está formatado errado, o app está muito desatualizado ou a conta está em estado restrito. Formatação de número é, de longe, a causa mais comum em campanhas de grande volume.
Nomes de exibição precisam ter relação com sua empresa verificada ou com uma marca comprovadamente sua. Termos genéricos, URLs, telefones, emojis e linguagem promocional são rejeitados. Use a razão social registrada ou um nome fantasia que seu site no ar sustente com clareza.
Em geral alguns minutos, mas pode chegar a 24 horas em períodos de pico, como Black Friday e Natal. Envie os templates de campanha pelo menos 48 horas antes de precisar deles.
Erro 131048. Muitas das suas mensagens recentes foram bloqueadas ou denunciadas, então a Meta reduziu sua vazão de envio. Pare imediatamente, identifique qual template ou segmento causou os bloqueios, limpe a lista e retome com volume menor.
O erro 132015 pausa um template por 3 horas na primeira ocorrência, 6 na segunda e 24 na terceira. Ele volta sozinho. Use o intervalo para corrigir a causa, normalmente qualidade de lista ou frequência. Depois de pausas demais, ele é desativado em definitivo (132016) e você vai precisar de um template novo com conteúdo diferente.
Comece pelo seu BSP. Clientes AiSensy têm suporte direto e a maioria dos casos se resolve ali. Para restrições de conta e recursos, você vai precisar falar com a Meta diretamente pelo Business Manager. Tenha sempre o fbtrace_id e o horário em mãos.
Links rápidos
- Como solicitar a API do WhatsApp Business
- Tipos de mensagens template do WhatsApp
- Plano Básico ou Plano Pro: qual escolher
- Chatbot no WhatsApp: o que é e como criar
- Agente de IA no WhatsApp vs chatbot
- Caixa de entrada multiagente para WhatsApp
- Anúncios no WhatsApp: guia completo
- Casos de uso da API do WhatsApp Business
- Biblioteca de templates de mensagem do WhatsApp
- (EN Version) WhatsApp Business API Errors: Causes & Fixes
