# Limites de envio

Fonte: https://apiwpp.com/docs/guias/limites-de-envio
Seção: Guias
Atualizado em: 2026-09-29

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](#requisicoes-a-api) | Requisições por IP de origem | `429` com `Retry-After` |
| [Cota do plano](#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](#ritmo-de-envio-de-cada-numero) | 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](https://apiwpp.com/docs/referencia/limites).

## 1. Requisiçõ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-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.

Resposta `429`

```json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded, retry in 38 seconds" }
```

Resposta `429`

```json
{ "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](https://apiwpp.com/docs/guias/idempotencia)).

## 2. Cota 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](#ritmo-de-envio-de-cada-numero) 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`](https://apiwpp.com/docs/api/mensagens/enviar-mensagem) 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`.

Resposta `429`

```json
{ "error": "Daily message limit exceeded (1098/1000, 3 queued)" }
```

Para acompanhar o consumo, [`GET /tenants/{id}/usage`](https://apiwpp.com/docs/api/uso/uso-do-projeto) 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`](https://apiwpp.com/docs/api/uso/uso-diario) traz o histórico por dia. As duas pedem o escopo `usage:read`. O guia [Uso e registros](https://apiwpp.com/docs/guias/uso-e-registros) mostra como usá-las.

## 3. Ritmo 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 `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](#destinatarios-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`](https://apiwpp.com/docs/api/mensagens/fila-do-numero): `limits`, `usage` e `warmup`.

**Consultar a fila e os limites do número**

```bash
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/queue \
  -H "Authorization: Bearer $API_KEY"
```

Resposta `200`

```json
{
  "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](https://apiwpp.com/docs/guias/parear-um-numero) 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 `5511988887777@s.whatsapp.net` é 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`](https://apiwpp.com/docs/webhooks/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:

Resposta `429`

```json
{
  "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`](https://apiwpp.com/docs/webhooks/message-delivery), com `reason: reachout_timelocked`, e não o tenta de novo;
- avisa o bloqueio com [`connection.status`](https://apiwpp.com/docs/webhooks/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`](https://apiwpp.com/docs/webhooks/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.

> **Não force o ritmo**
>
> Distribuir os mesmos envios por mais números, ou reenviar logo depois de uma recusa, é o caminho mais curto para o bloqueio e o banimento. Se o volume não cabe no ritmo de um número, fale com o suporte antes.

## 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 |

**Node.js**

```js
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'))
```

**cURL**

```bash
# -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](https://apiwpp.com/docs/referencia/limites): todos os números da apiwpp numa tabela só.
- [Idempotência](https://apiwpp.com/docs/guias/idempotencia): repetir um envio depois de um `429` sem duplicar a mensagem.
- [Erros](https://apiwpp.com/docs/guias/erros): os outros status e quando tentar de novo.
- [Referência: Fila do número](https://apiwpp.com/docs/api/mensagens/fila-do-numero): o formato completo de `limits`, `usage` e `warmup`.
