Pular para o conteúdo
apiwpp
Termo

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:

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.

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.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.