Limites e erros

Formato dos erros

Todo erro tem o mesmo formato:

{ "error": "invalid_token", "message": "Texto explicativo em português" }

• error é um código estável, em snake_case. Use este campo no seu código.
• message é um texto para humanos e pode mudar.

Códigos de status

Status	Significado
400	Dados da requisição inválidos (validation_error, invalid_json, invalid_phone e os códigos de mídia)
401	Token da instância ou token de segurança da conta ausente ou inválido
402	Instância suspensa ou com pagamento pendente
403	IP não autorizado ou conta bloqueada
404	Recurso não encontrado, como uma entrega de webhook ou uma rota que não existe
409	Operação incompatível com o estado atual da instância
413	Corpo da requisição grande demais
415	Tipo de conteúdo não aceito: envie application/json
422	Contato descadastrado
429	Muitas requisições
500	Erro interno (internal_error)

Os códigos de cada rota estão nas tabelas de erros dos guias de autenticação, conexão, envio de mensagens e envio de mídia.

Em validation_error, a message lista os campos com problema, como Dados inválidos: to, text.

Limite de requisições

Há limite de requisições por minuto por IP (hoje, 300) e por instância (hoje, 600). Ao excedê-lo, a API responde 429 com o código rate_limited e o cabeçalho Retry-After, que traz os segundos a esperar antes de tentar de novo.

Falhas seguidas de autenticação do mesmo IP também levam a 429: depois de muitos 401 num minuto, as chamadas desse IP são recusadas até a janela passar.

const resposta = await fetch(url, opcoes)
if (resposta.status === 429) {
  const segundos = Number(resposta.headers.get('retry-after') ?? 1)
  await new Promise((r) => setTimeout(r, segundos * 1000))
  // tente de novo
}

O envio de mensagens também passa por uma fila com ritmo controlado, para proteger o número. Por isso o 202 não significa envio imediato.

Tamanhos

Item	Limite
Texto de uma mensagem	10.000 caracteres
Legenda de mídia	1.024 caracteres
Mídia em base64 (decodificada)	16 MB
Corpo de uma requisição de mídia	25 MB
Corpo das demais requisições	1 MB
Telefones em POST /contacts/check	50 por chamada

Saúde do número

GET /v1/instances/{instanceId}/health mostra os contadores de envio e recebimento da instância, para você notar cedo se o número está enviando demais. A resposta traz today e last7Days (cada um com sent e received), byType e warning, que vale "high_send_ratio" quando o volume enviado está desproporcional ao recebido, ou null.

Boas práticas

• Faça as chamadas pelo seu servidor e guarde o token em variável de ambiente.
• Trate 429 esperando o tempo de Retry-After, e não tentando de novo em laço.
• Não repita um envio só porque não viu o webhook: consulte GET /queue e o histórico de entregas antes.
• Respeite o descadastro. Quem pede para sair e continua recebendo mensagens tende a denunciar o número.