# Limites

Fonte: https://apiwpp.com/docs/referencia/limites
Seção: Referência
Atualizado em: 2026-09-29

Todos os números da apiwpp numa página: requisições, cota, ritmo de envio por número, pareamento, chaves, webhooks, mídia e registros.

Esta página reúne todos os números da apiwpp para consulta rápida. Cada linha aponta para o guia que explica a regra. Todos são os **padrões** da apiwpp; os limites de envio por minuto, hora e dia de um projeto podem ser ajustados pela nossa equipe, e os que valem agora para um número estão em [`GET /connections/{id}/queue`](https://apiwpp.com/docs/api/mensagens/fila-do-numero).

## Requisições à API

Contadas por IP de origem, antes da autenticação. Detalhes em [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio#requisicoes-a-api).

| Limite | Padrão | Ao passar dele |
| --- | --- | --- |
| Requisições por IP | 600 por minuto (janela fixa) | `429` com `Retry-After` |
| Autenticações com falha (chave errada) por IP | 20 a cada 5 minutos | `429` com `Retry-After` pelo resto da janela |

As requisições com credencial (certa ou errada) e as anônimas têm cotas separadas. Toda resposta contada traz `x-ratelimit-limit`, `x-ratelimit-remaining` e `x-ratelimit-reset`.

## Cota do plano

Os planos LITE e PRO não têm cota de mensagens: esta seção vale só para planos com um limite diário ou mensal. Nesses, a cota é da organização e soma os envios de todos os projetos dela, com o dia e o mês contados em UTC. Detalhes em [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio#cota-do-plano).

| Limite | Padrão | Efeito |
| --- | --- | --- |
| Aviso de consumo | A partir de 80% do limite diário ou mensal | O envio é aceito com o cabeçalho `X-Usage-Warning` |
| Corte | 110% do limite (a margem absorve requisições simultâneas) | `429` com `X-Usage-Percent`, sem enfileirar |

## Ritmo de envio de cada número

Os limites por minuto, hora e dia **não recusam** o envio: a mensagem espera na fila. Só o limite de destinatários novos responde na hora. Detalhes em [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio#ritmo-de-envio-de-cada-numero).

| Regra | Padrão | Ao passar dele |
| --- | --- | --- |
| Envios por número | 3 por minuto, 60 por hora, 200 por dia | Espera na fila |
| Intervalo entre dois envios | Aleatório, de 3 a 8 segundos | Espera na fila |
| Mesmo destinatário | Pelo menos 30 segundos entre duas mensagens | Espera na fila |
| Destinatários novos | 100 por 24 horas | `429` `new_recipient_cap_reached` com `Retry-After` |
| Contato conhecido | Trocou mensagem com o número nos últimos 28 dias, depois da conexão atual | Não conta como destinatário novo |
| Pausa por falhas | 5 falhas seguidas (sem uma pausa de mais de 5 minutos entre elas) | A fila do número para por 1 hora e retoma sozinha |

### Aquecimento

Nos **14 dias** depois de conectado, um número segue limites menores. Detalhes em [Aquecimento de um número recém-conectado](https://apiwpp.com/docs/guias/limites-de-envio#aquecimento-de-um-numero-recem-conectado).

| 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 |
| Depois de 14 dias | 3 | 60 | 200 | 100 |

Nenhuma etapa passa dos limites normais do número. Parear de novo (outro número, ou o mesmo depois de um logout) recomeça o aquecimento e zera os contatos conhecidos.

Para ver os limites, o consumo e o aquecimento de um número agora:

**cURL**

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

**Node.js**

```js
const res = await fetch(`https://api.apiwpp.com/connections/${process.env.CONNECTION_ID}/queue`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
})
const { limits, usage, warmup } = await res.json()
console.log(`Hoje: ${usage.day}/${limits.perDay}; novos em 24 h: ${usage.newRecipients}/${limits.newRecipientsPerDay ?? '∞'}`)
if (warmup.isInWarmup) console.log('Em aquecimento até', new Date(warmup.endsAt).toISOString())
```

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 }
}
```

## Envio de mensagens

| Limite | Valor | Detalhes |
| --- | --- | --- |
| `clientRef` | Até 200 caracteres; reservado por 7 dias na conexão | [Idempotência](https://apiwpp.com/docs/guias/idempotencia) |
| Reserva provisória de um `clientRef` | Expira sozinha em 60 segundos se o enfileiramento não terminar | [Idempotência](https://apiwpp.com/docs/guias/idempotencia#o-que-a-reserva-cobre) |
| `typingDelay` | Padrão de 1500 milissegundos | [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens#texto) |
| Arquivo de `media.url` | Até 50 MB, download em até 30 segundos, até 3 redirecionamentos | [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens#midia) |
| Vínculo do `clientRef` com os status | 72 horas em [`message.delivery`](https://apiwpp.com/docs/webhooks/message-delivery) | [Idempotência](https://apiwpp.com/docs/guias/idempotencia#correlacionar-os-eventos) |

## Operações de mensagem (PRO)

Exigem um plano com operações de mensagem; sem ele, a resposta é `403` `plan_feature_required`. Detalhes em [Operações de mensagem](https://apiwpp.com/docs/guias/operacoes-de-mensagem).

| Limite | Valor | Ao passar dele |
| --- | --- | --- |
| Mensagens que podem ser editadas ou apagadas | Só as enviadas pela API por esta conexão nas últimas 72 horas | `404` |
| Janela de edição | 15 minutos depois do envio | `409` `edit_window_closed` |
| `text` da edição | De 1 a 4096 caracteres | `400` |
| `messageIds` em [marcar como lidas](https://apiwpp.com/docs/api/mensagens/marcar-como-lidas) | De 1 a 100 por chamada | `400` |

## Contatos

| Limite | Valor | Ao passar dele |
| --- | --- | --- |
| `phones` em [verificar números](https://apiwpp.com/docs/api/contatos/verificar-numeros) | Até 100 por chamada | `400` |

## Pareamento

Detalhes em [Parear um número](https://apiwpp.com/docs/guias/parear-um-numero#pareamento-por-codigo).

| Limite | Valor | Ao passar dele |
| --- | --- | --- |
| Código de pareamento | 8 caracteres, válido até `expiresAt` | Peça outro |
| Pedidos de código por conexão | Um a cada 30 segundos | `429` `pairing_code_too_soon` com `Retry-After` |
| Códigos por número de telefone | 5 por hora | `429` `pairing_code_too_soon` com `Retry-After` |
| `phone` do pedido de código | De 8 a 32 caracteres | `400` |
| Aquecimento depois do pareamento | 14 dias | Veja [Aquecimento](#aquecimento) |

## Chaves de API

Detalhes em [Autenticação](https://apiwpp.com/docs/autenticacao#criar-rotacionar-e-revogar-chaves).

| Limite | Valor |
| --- | --- |
| `name` da chave | De 1 a 100 caracteres |
| `scopes` | Pelo menos 1, e só escopos que a chave chamadora tem |
| `overlapSeconds` ao rotacionar | Padrão de 24 horas (`86400`), de 0 a 7 dias (`604800`) |
| Chaves revogadas ou expiradas na listagem | As 100 mais recentes |

## Webhooks

Detalhes em [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura#respostas-e-novas-tentativas).

| Limite | Padrão |
| --- | --- |
| Tempo para o seu endpoint responder `2xx` | 10 segundos |
| Tentativas por evento | 6 (a primeira e mais 5, depois de cerca de 2, 4, 8, 16 e 32 segundos) |
| Pausa das entregas do projeto | Depois de 5 falhas seguidas: 30 segundos, dobrando a cada teste que falha, até 5 minutos |
| Idade máxima de um evento não entregue | 24 horas, depois fica `dead` |
| Entregas esperando nova tentativa por projeto | 10 000; além disso, as novas falhas vão direto para `dead` |
| Tolerância de `X-Sales-Timestamp` no seu verificador | 300 segundos |
| Payload guardado no registro de entregas | Até 256 KB (maior que isso não pode ser reenviado) |
| [Reenviar entregas mortas](https://apiwpp.com/docs/api/registros/reenviar-entregas-mortas) | Até 1000 por chamada |
| [Testar webhook](https://apiwpp.com/docs/api/projetos/testar-webhook) | 10 segundos para o endpoint responder |

## Mídia recebida

| Limite | Padrão | Detalhes |
| --- | --- | --- |
| Validade da URL de `media.url` em [`message.incoming`](https://apiwpp.com/docs/webhooks/message-incoming) | 24 horas (até `media.expiresAt`) | [Baixar mídia](https://apiwpp.com/docs/api/midia/baixar-midia) |
| Arquivo guardado na apiwpp | 24 horas; depois a URL responde `404` | [Baixar mídia](https://apiwpp.com/docs/api/midia/baixar-midia) |

## Consultas, uso e registros

| Parâmetro | Valores | Operação |
| --- | --- | --- |
| `limit` | De 1 a 200, padrão 60 | [Listar mensagens](https://apiwpp.com/docs/api/registros/listar-mensagens), [Entregas de webhook](https://apiwpp.com/docs/api/registros/listar-entregas-de-webhook) |
| `days` | Padrão 30, no máximo 366 | [Uso do projeto](https://apiwpp.com/docs/api/uso/uso-do-projeto) |
| `days` | De 1 a 90, padrão 14 | [Uso diário](https://apiwpp.com/docs/api/uso/uso-diario) |
| `hours` | De 1 a 168, padrão 24 | [Histórico de heartbeats](https://apiwpp.com/docs/api/projetos/historico-de-heartbeats) |

| Dado | Retenção padrão |
| --- | --- |
| Registro de mensagens e registro de entregas de webhook (com os payloads) | 7 dias |
| Eventos de conexão (histórico de heartbeats) | 30 dias |
| Totais de uso | Não são apagados pela limpeza |

A limpeza roda a cada 6 horas, então uma linha pode durar algumas horas além do prazo. Detalhes em [Uso e registros](https://apiwpp.com/docs/guias/uso-e-registros#por-quanto-tempo-fica-guardado).

> **Planeje com folga**
>
> Os limites de ritmo protegem o número do banimento. Se o seu volume não cabe no ritmo de um número, fale com o suporte antes de distribuir os envios por mais números.

## Próximos passos

- [Limites de envio](https://apiwpp.com/docs/guias/limites-de-envio): por que cada limite existe e como saber qual `429` foi.
- [Códigos de erro](https://apiwpp.com/docs/referencia/codigos-de-erro): cada `error` e `code` que um limite pode devolver.
- [Cabeçalhos](https://apiwpp.com/docs/referencia/cabecalhos): `Retry-After`, `X-Usage-Percent`, `X-Usage-Warning` e os cabeçalhos de webhook.
