Limites
Requisições por minuto, tamanho de corpo, prazos e como tratar 429 com backoff.
Os limites protegem os seus números e a plataforma. São contados por conta (somando todas as chaves) em janelas de 60 segundos; a chave pode ter um limite próprio menor.
| Rota | Limite | Ao estourar |
|---|---|---|
POST /rpc/{Operação} e POST /messages/send | 120 por minuto por conta | 429 RATE_LIMITED |
| Limite próprio da chave (opcional) | 1 a 120 por minuto, em todas as rotas | 429 API_KEY_RATE_LIMITED |
POST /billing/quotes | 60 por minuto por conta | 429 RATE_LIMITED |
GET /media/{id} | 60 downloads por minuto por conta | 429 RATE_LIMITED |
GET /events | 10 aberturas de stream por minuto por conta | 429 RATE_LIMITED |
POST /sessions/create e /sessions/resume | 10 por minuto por conta | 429 RATE_LIMITED |
Tamanhos e prazos
| Item | Limite |
|---|---|
Corpo de /rpc, /messages/send e /billing/quotes | 12 MiB (acima: 413). Arquivos vão em Base64, que ocupa ~33% a mais. |
Corpo de /sessions/create e /sessions/resume | 4 KiB |
| Prazo de uma operação | 30 s (padrão). Envie deadlineMs (1 a 30000) para um prazo menor. |
| Download de mídia | 64 MiB |
| Stream de pareamento | 5 minutos |
| Stream de eventos | 1 hora por conexão; reconecte com Last-Event-ID. |
| Listas | Até 200 itens por página. |
Tratando 429
A resposta não traz Retry-After. Espere e tente de novo com backoff exponencial com variação aleatória (1 s, 2 s, 4 s, 8 s... até ~60 s), e reduza a concorrência. Para envios em massa, prefira campanhas: o Zynzap cuida do ritmo e dos intervalos entre mensagens.
// Repete chamadas com 429/503 com backoff exponencial e variação aleatória.
export async function withBackoff(call, { attempts = 6 } = {}) {
for (let attempt = 0; ; attempt++) {
const response = await call();
if (![429, 503].includes(response.status) || attempt === attempts - 1) return response;
const delay = Math.min(60_000, 1000 * 2 ** attempt) * (0.5 + Math.random() / 2);
await new Promise((resolve) => setTimeout(resolve, delay));
}
}Não repita automaticamente operações pagas que falharam com 503/504: o resultado pode ser incerto. Veja Erros.
Limites do WhatsApp
Além dos limites da API, o próprio WhatsApp limita números novos ou com envios em massa. Respeitar a API não garante que o número não será restrito: veja as boas práticas.