Pular para o conteúdo

Limites de envio

O limite de requisições da API, a cota do plano e o ritmo de envio que protege cada número do banimento, com os 429 de cada um.

Ver em Markdown

Há três limites diferentes, cada um com o seu motivo, e cada um responde 429 de um jeito:

LimiteContaAo passar dele
Requisições à APIRequisições por IP de origem429 com Retry-After
Cota do planoMensagens da organização por dia e por mês, só em planos com limite de mensagens429 com X-Usage-Percent
Ritmo de envio do númeroEnvios e destinatários novos de cada númeroOs envios esperam na fila; destinatários novos demais: 429 new_recipient_cap_reached

Os planos LITE e PRO não têm cota de mensagens, nem diária nem mensal: neles, só o limite de requisições e o ritmo de envio de cada número valem. Todos os valores deste guia são os padrões da apiwpp. A tabela completa, com cada número, está em Limites.

1Requisições à API

Contadas por IP de origem, antes da autenticação:

LimitePadrãoAo passar dele
Requisições600 por minuto429 com Retry-After
Autenticações com falha (chave errada)20 a cada 5 minutos429 com Retry-After pelo resto da janela
  • As requisições que enviam uma credencial (certa ou errada) dividem uma cota por IP, e as anônimas, outra. Vários sistemas atrás do mesmo IP (um NAT compartilhado) dividem a mesma cota.
  • A janela é fixa: começa na primeira requisição e dura um minuto.
  • Toda resposta contada traz x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset (segundos até a janela recomeçar). Use-os para desacelerar antes do 429.
  • Só uma chave errada conta como falha de autenticação; uma requisição sem chave, não. Uma chave certa nunca é barrada pelo limite de falhas, só pelo de requisições.
429
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded, retry in 38 seconds" }
429
{ "error": "Too many failed authentication attempts" }

Nos dois casos, espere os segundos de Retry-After e repita. Um envio repetido com o mesmo clientRef não duplica a mensagem (veja Idempotência).

2Cota do plano

Os planos LITE e PRO não têm limite de mensagens, então esta seção não se aplica a eles: só o ritmo de envio de cada número limita os envios. A cota existe só em planos com um limite diário ou mensal de mensagens.

Nesses planos, o limite é da organização: as mensagens de todos os projetos dela contam juntas para os limites diário e mensal, com o dia e o mês contados em UTC. As mensagens já enfileiradas e ainda não enviadas também contam, para uma rajada não passar do limite antes de sair. Só os envios contam; as mensagens recebidas, não.

  • A partir de 80% de um dos limites, POST /connections/{id}/send continua aceitando e traz o cabeçalho X-Usage-Warning (por exemplo, Approaching limit: 85% used).
  • Ao chegar a 110% do limite (a margem absorve requisições simultâneas), o envio responde 429 com X-Usage-Percent e não enfileira nada. O limite mensal é conferido antes do diário.
  • Um plano sem limite de mensagens, como o LITE e o PRO, nunca recebe esse 429 nem o X-Usage-Warning.
429
{ "error": "Daily message limit exceeded (1098/1000, 3 queued)" }

Para acompanhar o consumo, GET /tenants/{id}/usage mostra o uso do dia e do mês do projeto e da organização, com o plano e o percentual de cada limite; GET /usage/daily traz o histórico por dia. As duas pedem o escopo usage:read. O guia Uso e registros mostra como usá-las.

3Ritmo de envio de cada número

O WhatsApp bane números que enviam como robôs. Por isso cada número tem uma fila que espaça os envios. O POST /connections/{id}/send responde na hora com o lugar na fila (position) e o horário previsto (scheduledAt, em milissegundos Unix); o envio acontece depois, e o resultado chega pelos webhooks.

RegraPadrão
Envios por número3 por minuto, 60 por hora, 200 por dia
Intervalo entre dois enviosaleatório, de 3 a 8 segundos
Mesmo destinatáriopelo menos 30 segundos entre duas mensagens
Destinatários novos (que não trocaram mensagem com o número)100 por 24 horas
  • Os limites por minuto, hora e dia não recusam o envio: a mensagem espera na fila até a janela abrir. Cada janela começa no primeiro envio dela e dura um minuto, uma hora ou 24 horas.
  • O scheduledAt considera o intervalo entre envios e o intervalo do mesmo destinatário. Se o número já alcançou o limite da hora ou do dia, o envio sai mais tarde que o previsto.
  • Só o limite de destinatários novos recusa o envio na hora (veja Destinatários novos por dia).
  • A nossa equipe pode ajustar os limites por minuto, hora e dia de um projeto. Os que valem para um número agora estão em GET /connections/{id}/queue: limits, usage e warmup.
bashConsultar a fila e os limites do número
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/queue \
  -H "Authorization: Bearer $API_KEY"
200
{
  "pending": 1,
  "scheduled": 2,
  "limits": { "perMinute": 3, "perHour": 60, "perDay": 200, "newRecipientsPerDay": 100 },
  "usage": { "minute": 1, "hour": 12, "day": 40, "newRecipients": 7 },
  "warmup": { "createdAt": 1789646400000, "messagesSent": 40, "isInWarmup": false, "endsAt": 1790856000000 }
}

limits.newRecipientsPerDay vem null quando o número não tem limite de destinatários novos. warmup.createdAt é quando o número foi conectado, e warmup.endsAt, quando o aquecimento acaba.

Aquecimento de um número recém-conectado

Durante os 14 dias depois de conectado (pareado), um número segue limites menores, que sobem aos poucos:

Desde a conexãoPor minutoPor horaPor diaDestinatários novos por 24 horas
Até 6 horas15205
6 a 24 horas1105010
1 a 3 dias12010020
3 a 7 dias13015030
7 a 14 dias24520050

Nenhuma etapa passa dos limites normais do número. Conectar outro número, ou o mesmo depois de um logout, começa o aquecimento de novo, e as contagens por minuto, hora e dia recomeçam do zero. Planeje campanhas para depois dos 14 dias; o guia Parear um número trata da conexão.

Destinatários novos por dia

Um contato é conhecido quando trocou mensagem com o número nos últimos 28 dias e depois da conexão atual do número: escreveu para ele, recebeu uma mensagem digitada no celular ou recebeu um envio da API que de fato saiu. Qualquer outro é um destinatário novo. Em detalhe:

  • Parear de novo zera os contatos conhecidos. Depois de um logout, ou de o WhatsApp encerrar a sessão, a conexão seguinte começa do zero, mesmo que seja o mesmo número: todos os contatos voltam a ser destinatários novos (e o aquecimento recomeça).
  • Conversas antigas contam pelo registro de mensagens, que guarda os últimos 7 dias por padrão: quem não falou com o número nesse período conta como novo no primeiro envio. Depois que esse envio sai, o contato passa a ser conhecido.
  • O nono dígito não engana o limite. Um celular brasileiro é o mesmo contato com ou sem o 9 (5511988887777 e 551188887777), e o JID [email protected] é o mesmo contato que o telefone 5511988887777.
  • Quem escreveu com um identificador sem telefone (@lid) passa a ser conhecido pelo telefone assim que o telefone é descoberto (contact.resolved).
  • Grupos, listas de transmissão e canais nunca contam.

Cada destinatário novo conta uma vez a cada 24 horas, no momento em que o envio é aceito. Quando o número já alcançou o limite de destinatários novos das últimas 24 horas, um envio para mais um responde na hora, sem enfileirar nada:

429
{
  "error": "new_recipient_cap_reached",
  "message": "This number already reached 100 new recipients (people it exchanged no message with in the last 28 days since its current link; a re-pair makes every contact new) in the last 24 hours; reaching out to more gets it restricted by WhatsApp. Retry after Retry-After seconds"
}

O Retry-After traz os segundos até uma vaga abrir ou, durante o aquecimento, até a próxima etapa aumentar o limite, o que vier antes. Um contato conhecido nunca é barrado por esse limite, e usage.newRecipients em GET /connections/{id}/queue mostra quantos destinatários novos o número alcançou nas últimas 24 horas.

Um to que não é telefone nem JID de pessoa, grupo, lista de transmissão ou canal responde 400 com error: invalid_recipient antes de qualquer contagem.

Pausa automática por falhas

Quando os envios de um número falham em sequência (5 falhas sem uma pausa de mais de 5 minutos entre elas, descontado cada envio que deu certo no meio), a fila desse número para por 1 hora e depois retoma sozinha. As mensagens continuam na fila. Um envio recusado porque o número não está no WhatsApp ou por bloqueio de novas conversas não conta para essa pausa.

Bloqueio temporário de novas conversas

Mensagens para contatos que nunca falaram com o número (contatos frios) podem ser recusadas pelo WhatsApp com o erro 463, e contas que insistem entram num bloqueio temporário de novas conversas (reach-out timelock). A apiwpp:

  • informa o failed do envio recusado em message.delivery, com reason: reachout_timelocked, e não o tenta de novo;
  • avisa o bloqueio com connection.status reason: reachout_timelock e o fim previsto em reachoutTimelock.endsAt, e o fim dele com reason: reachout_timelock_lifted;
  • enquanto o bloqueio durar, recusa os envios da fila sem tentá-los (cada tentativa aprofundaria a restrição), com message.send_failed reason: reachout_timelocked para os que têm clientRef.

Reenvie depois de endsAt, com um clientRef novo. Para evitar o bloqueio, comece conversas só com quem espera a sua mensagem: o limite de destinatários novos por dia existe para isso.

Qual 429 foi

O cliente decide pelo corpo e pelos cabeçalhos da resposta, nunca pelo texto de message:

Sinal na respostaLimiteO que fazer
X-Usage-PercentCota do plano (só em planos com limite de mensagens)Não repita até o dia (ou o mês) virar em UTC, ou mude de plano
error: new_recipient_cap_reached e Retry-AfterDestinatários novos do númeroEspere Retry-After, ou envie a contatos conhecidos
error: Too many failed authentication attempts e Retry-AfterFalhas de autenticaçãoCorrija a chave; espere Retry-After
Só Retry-After (com x-ratelimit-remaining: 0)Requisições à APIEspere Retry-After e repita
async function classify429(res) {
  const body = await res.json().catch(() => ({}))
  const retryAfter = Number(res.headers.get('retry-after')) || null

  if (res.headers.has('x-usage-percent')) {
    return { kind: 'plan_quota', usagePercent: Number(res.headers.get('x-usage-percent')) }
  }
  if (body.error === 'new_recipient_cap_reached') {
    return { kind: 'new_recipients', retryAfter }
  }
  if (body.error === 'Too many failed authentication attempts') {
    return { kind: 'auth_failures', retryAfter }
  }
  return { kind: 'request_rate', retryAfter }
}

const res = await fetch(`https://api.apiwpp.com/connections/${process.env.CONNECTION_ID}/send`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ to: '5511988887777', message: 'Olá!', clientRef: 'pedido-1234' }),
})

if (res.status === 429) console.log(await classify429(res))
else if (res.headers.has('x-usage-warning')) console.warn(res.headers.get('x-usage-warning'))

Próximos passos

Esta página ajudou? · Atualizado em 29 set 2026