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.
Há três limites diferentes, cada um com o seu motivo, e cada um responde 429 de um jeito:
| Limite | Conta | Ao passar dele |
|---|---|---|
| Requisições à API | Requisições por IP de origem | 429 com Retry-After |
| Cota do plano | Mensagens da organização por dia e por mês, só em planos com limite de mensagens | 429 com X-Usage-Percent |
| Ritmo de envio do número | Envios e destinatários novos de cada número | Os 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:
| Limite | Padrão | Ao passar dele |
|---|---|---|
| Requisições | 600 por minuto | 429 com Retry-After |
| Autenticações com falha (chave errada) | 20 a cada 5 minutos | 429 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-remainingex-ratelimit-reset(segundos até a janela recomeçar). Use-os para desacelerar antes do429. - 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.
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded, retry in 38 seconds" }{ "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}/sendcontinua aceitando e traz o cabeçalhoX-Usage-Warning(por exemplo,Approaching limit: 85% used). - Ao chegar a 110% do limite (a margem absorve requisições simultâneas), o envio responde
429comX-Usage-Percente 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
429nem oX-Usage-Warning.
{ "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.
| Regra | Padrão |
|---|---|
| Envios por número | 3 por minuto, 60 por hora, 200 por dia |
| Intervalo entre dois envios | aleatório, de 3 a 8 segundos |
| Mesmo destinatário | pelo 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
scheduledAtconsidera 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,usageewarmup.
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/queue \
-H "Authorization: Bearer $API_KEY"{
"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ão | Por minuto | Por hora | Por dia | Destinatários novos por 24 horas |
|---|---|---|---|---|
| Até 6 horas | 1 | 5 | 20 | 5 |
| 6 a 24 horas | 1 | 10 | 50 | 10 |
| 1 a 3 dias | 1 | 20 | 100 | 20 |
| 3 a 7 dias | 1 | 30 | 150 | 30 |
| 7 a 14 dias | 2 | 45 | 200 | 50 |
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 (
5511988887777e551188887777), e o JID[email protected]é o mesmo contato que o telefone5511988887777. - 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:
{
"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
faileddo envio recusado emmessage.delivery, comreason: reachout_timelocked, e não o tenta de novo; - avisa o bloqueio com
connection.statusreason: reachout_timelocke o fim previsto emreachoutTimelock.endsAt, e o fim dele comreason: reachout_timelock_lifted; - enquanto o bloqueio durar, recusa os envios da fila sem tentá-los (cada tentativa aprofundaria a restrição), com
message.send_failedreason: reachout_timelockedpara os que têmclientRef.
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 resposta | Limite | O que fazer |
|---|---|---|
X-Usage-Percent | Cota 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-After | Destinatários novos do número | Espere Retry-After, ou envie a contatos conhecidos |
error: Too many failed authentication attempts e Retry-After | Falhas de autenticação | Corrija a chave; espere Retry-After |
Só Retry-After (com x-ratelimit-remaining: 0) | Requisições à API | Espere 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'))# -i mostra os cabeçalhos: Retry-After, X-Usage-Percent, X-Usage-Warning e x-ratelimit-*
curl -si -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/send \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "5511988887777", "message": "Olá!", "clientRef": "pedido-1234"}'Próximos passos
- Limites: todos os números da apiwpp numa tabela só.
- Idempotência: repetir um envio depois de um
429sem duplicar a mensagem. - Erros: os outros status e quando tentar de novo.
- Referência: Fila do número: o formato completo de
limits,usageewarmup.