O que é rate limit
Rate limit é o número máximo de requisições ou de ações que uma API aceita de um mesmo cliente num intervalo de tempo. Quando o teto é atingido, a API recusa as chamadas seguintes, em geral com o status 429 e o cabeçalho Retry-After.
Atualizado em
Rate limit (limite de taxa) é a regra que define quantas requisições, ou quantas ações, uma API aceita de um mesmo cliente num intervalo de tempo: por segundo, por minuto, por hora ou por dia. Passado esse teto, as chamadas seguintes são recusadas até a janela abrir de novo.
Quase toda API pública tem algum rate limit. Ele protege o serviço de sobrecarga, impede que um cliente com defeito, num laço infinito por exemplo, prejudique os outros e dificulta ataques de força bruta contra as chaves de API.
O status 429 e o cabeçalho Retry-After
O jeito padrão de uma API HTTP avisar que o limite foi atingido é responder com o status 429 Too Many Requests. Muitas APIs incluem também o cabeçalho Retry-After, com o número de segundos que o cliente deve esperar antes de tentar de novo.
A forma correta de tratar um 429 é respeitar esse tempo, e não repetir a chamada imediatamente, o que só prolonga o bloqueio:
const response = await fetch(`https://api.apiwpp.com/connections/${connectionId}/send`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.APIWPP_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ to: '5511988887777', message: 'Seu pedido saiu para entrega.', clientRef: 'pedido-1234' }),
})
if (response.status === 429) {
const seconds = Number(response.headers.get('retry-after') ?? 60)
const { error } = await response.json() // e.g. "new_recipient_cap_reached"
// Schedule a new attempt in `seconds`, reusing the same clientRef
}
Reaproveitar o mesmo clientRef na nova tentativa garante que a mensagem não saia duas vezes, mesmo que a primeira chamada tenha sido aceita sem você saber. Esse é o papel da idempotência.
Os três limites da apiwpp
Na apiwpp, "limite" pode significar três coisas diferentes, cada uma com o seu motivo:
- Requisições à API. Contadas por IP de origem: por padrão, 600 requisições por minuto e 20 autenticações com falha a cada 5 minutos. Passou disso, a resposta é
429comRetry-After. Uma chave válida nunca é barrada pelo limite de falhas, só pelo de requisições. - Cota de mensagens. O mecanismo de cota existe na API, mas nos planos LITE e PRO não há cota nem cobrança por mensagem: as mensagens são ilimitadas dentro do ritmo de envio de cada número.
- Ritmo de envio por número. É o limite que mais importa no dia a dia. Por padrão, cada número envia até 3 mensagens por minuto, 60 por hora e 200 por dia, com intervalo aleatório de 3 a 8 segundos, pelo menos 30 segundos entre duas mensagens ao mesmo destinatário e no máximo 100 destinatários novos a cada 24 horas.
Rate limit da API x ritmo de envio
Os dois parecem a mesma coisa, mas funcionam de forma oposta.
O rate limit da API recusa: a chamada volta com 429 e nada acontece. Ele protege o serviço.
O ritmo de envio não recusa a mensagem, ele a espaça. O POST /connections/{id}/send aceita o envio na hora, responde 202 com o lugar na fila (position) e o horário previsto (scheduledAt), e a fila anti-bloqueio solta as mensagens no ritmo do número. Ele protege o número, porque o WhatsApp restringe contas que enviam como robôs.
A exceção é o teto de destinatários novos: quando o número já falou com 100 pessoas novas nas últimas 24 horas, um envio para mais uma responde 429 com o erro new_recipient_cap_reached e Retry-After, e nada entra na fila. Contatos conhecidos nunca são barrados por esse teto. Nos primeiros 14 dias depois da conexão, os limites são menores e sobem por etapa: é o aquecimento de número.
Os limites em vigor para um número estão em GET /connections/{id}/queue, com os campos limits, usage e warmup.
Perguntas frequentes
O que significa o erro 429?
Significa que um limite foi atingido e a chamada foi recusada. Na apiwpp, o 429 pode vir do limite de requisições por IP, de autenticações com falha demais ou do teto de destinatários novos do número. O cabeçalho Retry-After diz quantos segundos esperar.
A apiwpp limita quantas mensagens posso enviar por mês?
Não há cota mensal nos planos LITE e PRO: as mensagens são ilimitadas e o preço é por número. O que existe é o ritmo de envio de cada número, que espaça as mensagens para reduzir o risco de bloqueio.
Posso aumentar o limite de envio de um número?
O ritmo existe para proteger o número, e passar dele aumenta o risco de restrição pelo WhatsApp. Para enviar mais, distribua os envios entre mais números. O guia como evitar o bloqueio do número explica as boas práticas.
Outros termos
Todos: Glossário →Aquecimento de número (ou de chip) é o período depois de conectar um WhatsApp em que os limites de envio começam baixos e sobem aos poucos, para o número ganhar histórico antes de chegar ao volume normal. Na apiwpp, ele dura 14 dias e é aplicado pela fila.
Uma operação é idempotente quando repeti-la tem o mesmo efeito que fazê-la uma vez. Em APIs, isso se consegue com uma chave de idempotência: o cliente manda o mesmo identificador em cada tentativa e o servidor reconhece a repetição em vez de executar de novo.
Webhook é uma chamada HTTP que um serviço faz para um endereço do seu sistema quando um evento acontece, como uma mensagem recebida. Em vez de perguntar de tempos em tempos se há novidades, o seu sistema é avisado na hora.