Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Começar

Erros e limites da API de WhatsApp

Tabela de erros da API de WhatsApp, limites por categoria, a trava de contato novo e as boas práticas que reduzem o risco de restrição do número.

12 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Todo erro vem como { "ok": false, "error": "…", "message": "…" }, e você programa pelo error e pelo código HTTP. Os limites padrão são 10 mensagens por minuto e 500 por dia no envio, 60 por minuto nas ações e 120 por minuto nas leituras. A trava de contato novo dura cerca de 6 horas.

Recurso em beta: pode mudar. Os erros e tetos marcados como novos (mídia, grupos, contatos, conversas e agendamento, da versão 1.1; status, consulta de avisos, aprovação, IPs permitidos, etiquetas, bots e sandbox, da 1.2) podem ser ajustados durante o teste.

Esta página é a de consulta: o formato do erro, o que cada código quer dizer, quanto cada tipo de chamada pode fazer e como se comportar para não ser restringido. A base é https://proxybox.com.br/api/whatsapp/v1.

Como é o formato do erro?

Sempre o mesmo: ok falso, um código estável em error e uma frase em português em message.

Toda falha volta no mesmo formato, com ok falso, um código estável em error e uma mensagem em português:

json
{ "ok": false, "error": "rate_limited", "message": "Limite de 10 mensagens por minuto.", "retry_after": 14 }

Programe pelo error e pelo código HTTP, nunca pela message, que pode mudar de redação. Em erros de campo, vem também fields, a lista dos campos com problema. A API não devolve detalhes internos nem nomes de sistemas por trás dela.

Quais são todos os erros e o que fazer?

A tabela abaixo reúne cada código, o HTTP, o significado e a ação.

HTTP error Significa O que fazer
401 invalid_key Chave ausente, errada ou de instância cancelada Conferir a chave; se trocou, atualizar o sistema
403 instance_paused A equipe pausou a instância Falar com o suporte
422 interactive_unsupported Lista (menu) ou carrossel: o WhatsApp mostra "mensagem incompatível"; nada é enviado Usar botões de resposta, link, copiar ou ligar (botões)
403 ip_not_allowed O IP de quem chama não está nos IPs permitidos da chave Ajustar a lista no painel ou chamar do IP correto
403 status_disabled Publicação de status desligada na instância Ligar status_enabled nos ajustes
403 sandbox_expired O sandbox de 30 dias venceu Contratar uma instância de verdade
403 forbidden (aprovar/rejeitar) O pedido veio do conector de IA, que não pode decidir Aprovar pelo painel ou com a chave, sem o cabeçalho do conector
403 not_group_admin Ação de grupo, e o número da instância não é administrador Tornar o número administrador ou pedir a quem é
403 forbidden O WhatsApp não permitiu a ação (fora de grupos) Conferir se a ação é permitida para esse contato
404 not_found Mensagem, grupo, contato ou agendamento inexistente Conferir o identificador
404 unknown_operation A operação não existe Conferir o caminho da rota
409 not_connected Instância sem número conectado Ler o QR de novo no painel
409 new_contacts_locked O WhatsApp restringiu contatos novos (ou a trava ainda está ligada) e o destino não é um contato recente Esperar retry_after ou enviar só a contatos recentes
409 opted_out O telefone está na lista de não perturbe; nada foi enviado Não insistir
404 not_available Recurso ainda desligado, como a criação de instância por API Aguardar o lançamento; nada foi cobrado
409 not_cancelable Agendamento que já saiu, falhou ou foi cancelado Nada a fazer; consulte o estado
422 invalid_request Campo faltando ou inválido Corrigir os campos indicados em fields
422 number_not_on_whatsapp O telefone não tem WhatsApp Remover da lista; use a verificação de número
422 media_unavailable Não baixou o arquivo, endereço negado, tipo ou tamanho inválido Conferir o link e o tipo; veja enviar mídia
422 media_too_large Arquivo acima do limite do tipo Reduzir o arquivo
422 approval_queue_full Já há 100 mensagens esperando aprovação Aprovar ou rejeitar as pendentes
422 approval_chat_full Já há 10 pendentes para o mesmo contato Decidir as pendentes dele
422 approval_media_url_only Mídia em pedido com aprovação só vale por url Enviar a mídia por endereço, não por base64
410 (aprovação vencida) O prazo para aprovar acabou Pedir o envio de novo
422 schedule_in_past A data do agendamento já passou Usar uma data futura
422 schedule_too_far Mais de 30 dias à frente Agendar mais perto da data
422 schedule_limit Já existem 200 agendamentos pendentes Esperar enviarem ou cancelar
429 rate_limited Limite por minuto ou por hora Esperar retry_after segundos
429 daily_limit Limite do dia Esperar retry_after ou o dia seguinte
429 too_many_waiters Já há 3 esperas (wait) abertas em GET /events Esperar 2 segundos ou consultar sem wait
501 unsupported "Este recurso ainda não está disponível nesta instância." Usar outro caminho; veja o guia do recurso
502 engine_unavailable Serviço temporariamente fora do ar; nada foi enviado Tentar de novo com Idempotency-Key
503 instance_preparing Instância ainda sendo preparada Aguardar
504 timeout O WhatsApp demorou para confirmar. Em envio, a mensagem pode ter saído Conferir antes de reenviar, para não duplicar

Erro que parece sucesso: o tempo esgotado

Se o WhatsApp demora para confirmar um envio, a API responde 504 e a mensagem pode ou não ter saído. Não reenvie às cegas. Use sempre o cabeçalho Idempotency-Key (até 64 caracteres) nos envios: a mesma chave em até 24 horas devolve a resposta original sem enviar de novo.

Por que recebo 403 de um cliente HTTP, antes de chegar na API?

Clientes HTTP que usam o agente padrão do urllib do Python podem receber 403 do Cloudflare, que fica na frente do site, antes de a requisição chegar à API (a resposta não é um JSON { ok:false … }). Use requests ou defina um User-Agent próprio no cabeçalho. Os pacotes de SDK gerados já definem um.

Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.

Testar grátis

Quais são os limites por categoria?

Valem por instância; o cliente só reduz. A tabela mostra os tetos de envio, ações, leituras, consultas, administração de grupo e agendamento.

Os limites valem por instância. O cliente pode deixar mais devagar no painel, nunca mais rápido.

Categoria O que entra Teto padrão
Envio texto, mídia, voz, localização, contato, link, enquete, encaminhar 10 por minuto, 500 por dia, pausa de 3 a 10 segundos entre mensagens, um envio por vez
Ações leves reagir, editar, apagar, ler, estrelar, "digitando…", fixar, arquivar, trocar nome e foto 60 por minuto
Leituras listar conversas, mensagens, grupos, contatos, baixar mídia recebida 120 por minuto
Consulta de número verificar se tem WhatsApp 300 números por dia
Consulta de perfil perfil, foto, perfil comercial 120 por dia, com 0,3 segundo de intervalo mínimo
Administração de grupo adicionar, remover, nome, foto, trava, link 60 por hora
Grupo: criar / adicionar / entrar POST /groups, adicionar participantes, POST /groups/join 10 por dia / 50 participantes por dia / 20 por dia
Agendamento mensagens pendentes 200 por instância; até 30 dias à frente

Cada mídia conta como uma mensagem. O envio para um mesmo destino em sequência rápida não é bloqueado, mas o teto do dia vale. Não existe rota de lista nem de envio para todos.

Passou do teto: 429, com retry_after em segundos.

Quais limites chegaram na versão 1.2?

Todos em beta e por instância; os que o cliente configura só podem ser reduzidos, nunca aumentados.

O quê Limite
Status 3 publicações por dia; texto até 700 caracteres; nunca agendável
Botões Texto do botão até 25 caracteres; até 10 botões; lista e carrossel recusados (interactive_unsupported); mesmo ritmo do envio
Consulta de avisos limit até 100; wait até 25 s; 3 esperas por vez; avisos guardados 7 dias
Agrupar mensagens buffer_seconds de 0 a 30; espera máxima de 3 vezes o valor
Atividade limit até 200; histórico de 30 dias; métricas de 1 a 30 dias
IPs permitidos Até 20 IPs ou faixas
Etiquetas 50 por instância; 500 conversas por etiqueta
Aprovação humana 100 pendentes por instância; 10 por contato; prazo de 1 a 72 horas (padrão 24)
Bots 20 respostas por hora em cada conversa; 200 por dia; 15 s de espera ao bot
Armazenamento S3 Arquivo até 25 MB
Sandbox 100 envios por dia; 30 dias; 1 por conta; 60 simulações de mensagem por hora
Pareamento pela API QR e código: 12 por minuto; reiniciar: 5 por minuto; desconectar: 3 por hora

O que é a trava de contato novo?

Uma proteção que, depois de uma restrição do WhatsApp, envia só para telefones vistos nos últimos 60 dias, por cerca de 6 horas. O guia restrição 463 tem o passo a passo.

O WhatsApp, às vezes, restringe um número por um tempo e deixa de aceitar mensagem para contatos novos (pessoas com quem o número ainda não conversou), sem derrubar as conversas que já existem. Quando isso acontece, a API:

  1. Responde o envio que sofreu a restrição com 409 new_contacts_locked, registra a restrição no histórico da instância e marca a instância com risco alto no painel.
  2. Manda o aviso automático number.restricted para o seu sistema.
  3. Durante cerca de 6 horas (renovadas se a restrição voltar), envia só para telefones vistos nos últimos 60 dias (quem recebeu uma mensagem sua ou escreveu para você). Para qualquer outro, devolve 409 new_contacts_locked com retry_after.
  4. Mantém funcionando o envio para grupos, que não é afetado.

O objetivo é proteger o número enquanto a restrição dura: insistir em contato novo nessa hora costuma prolongá-la. A trava não destrava nada por conta própria; ela só evita que o seu sistema bata na parede.

O que é o vigia de conexão?

Uma verificação a cada 5 minutos de que a instância conectada responde de verdade; três falhas seguidas disparam a reconexão.

De 5 em 5 minutos a API confere se cada instância conectada responde de verdade ao WhatsApp, e não só se o aplicativo diz estar conectado. Se a resposta falhar três vezes seguidas, ela tenta reconectar. Se ainda assim não voltar, a instância fica em estado de erro, a equipe recebe um alerta e você recebe o aviso connection.updated. Uma falha isolada nunca derruba a instância.

Para consultar na hora: GET /health devolve se a instância está conectada, o tempo de uma ida e volta real ao WhatsApp em milissegundos e se ela está "surda" (deaf: conectada, mas sem resposta).

O que é o placar de risco da instância?

É uma nota simples do uso da sua instância: Tranquilo, Atenção ou Alto risco. Aparece no painel (cartão "Sinais do número") e em GET /instance, no campo risk, com os motivos em português e uma dica do que fazer.

Os sinais vêm só do que a ProxyBox já registra, sem consultar o WhatsApp: volume do dia perto do limite, proporção de envios que falharam, quase toda mensagem indo para uma pessoa diferente, pedidos para não receber mais, número novo mandando muito, quedas e reconexões e mensagens de madrugada. Se o próprio WhatsApp restringir ou desconectar o número, isso entra como Alto risco.

  • São sinais, não garantia. Tranquilo não quer dizer que o número não será bloqueado, e Alto risco não quer dizer que será. O WhatsApp decide sozinho.
  • Aviso: quando a instância chega a Alto risco, avisamos o dono por e-mail e no painel, no máximo uma vez por dia. Desligue em Ajustes ou com risk_alert: false.
  • Atualização: a nota é recalculada a cada minuto, no máximo.

Que boas práticas reduzem o risco?

Escrever só para quem espera receber, respeitar o ritmo, variar o texto e usar Idempotency-Key. Nada disso é garantia.

Nada abaixo é garantia. É o que reduz o risco e o que, na prática, explica a maior parte dos bloqueios (leia WhatsApp banido: causas na API e no Business).

  • Escreva só para quem espera receber e atenda quem pedir para parar.
  • Verifique o número antes de enviar a uma lista nova, com a verificação de contatos.
  • Varie o texto. Mensagem idêntica para muita gente é um dos sinais que o WhatsApp mais observa. Personalize com nome e dado do cliente.
  • Respeite o ritmo. Esperar o retry_after custa segundos; perder o número custa dias.
  • Comece devagar com número novo. Um número recém-conectado que dispara no primeiro dia chama atenção.
  • Trate 409 e 429. Quando a instância desconectar ou travar, pare a fila do seu lado em vez de insistir.
  • Use Idempotency-Key para uma nova tentativa não virar mensagem duplicada.
  • Não use o número principal do negócio nem o seu telefone pessoal.
  • Cuidado com grupos: não adicione ninguém sem pedido; criar e encher grupos em ritmo alto é comportamento que o WhatsApp observa.
  • Não use a API para mensagem em massa. Não é só boa prática: a política de uso aceitável proíbe.

Se o número for bloqueado pelo WhatsApp, a ProxyBox não consegue desfazer e não reembolsa por isso.

Veja também

Índice completo: índice dos guias. Sobre o produto: contratar uma instância de WhatsApp.

Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026, contra o catálogo da versão 1.2 da API.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp