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:
{ "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átisQuais 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:
- 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. - Manda o aviso automático
number.restrictedpara o seu sistema. - 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_lockedcomretry_after. - 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_aftercusta 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-Keypara 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
- Erro 463 do WhatsApp (contato novo): o que fazer
- Não perturbe e recusar chamadas: API de WhatsApp
- Equipe, papéis e métricas da API de WhatsApp
- Referência da API de WhatsApp v1.2: rotas
Í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.