> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ar-online.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limit

> Política de limites de taxa da API, limites por endpoint e como cadastrar seu IP na whitelist.

Para garantir estabilidade, performance e segurança da plataforma, todas as requisições estão sujeitas a limites de taxa (rate limit).

## Requisitos obrigatórios

* **Token de autenticação válido** em todas as requisições, independentemente de whitelist.
* A **whitelist** é aplicada exclusivamente por **IP de origem** previamente cadastrado.

<Warning>
  O limite padrão (sem whitelist) pode inviabilizar operações em produção. Para uso produtivo, é necessário o cadastro do IP de origem na whitelist.
</Warning>

## Limites por endpoint

### Clientes com IP em whitelist

| Método | Endpoints                                                                                                                              | Limite                   | Burst  |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | ------ |
| POST   | `/gw/email`, `/live/email`                                                                                                             | 0,5 req/s (1 a cada 2s)  | 20 req |
| GET    | `/gw/full/{idEmail}`, `/gw/email/{idEmail}`, `/gw/sms/{idEmail}`, `/gw/whatsapp/{idEmail}`, `/gw/voz/{idEmail}`, `/gw/carta/{idEmail}` | 0,1 req/s (1 a cada 10s) | 20 req |

### IPs fora da whitelist (padrão)

| Endpoints               | Limite                       | Burst |
| ----------------------- | ---------------------------- | ----- |
| Todos os listados acima | \~0,011 req/s (1 a cada 90s) | 5 req |

## Retorno HTTP 429

Quando o limite é excedido, a API retorna `HTTP 429 Too Many Requests`. Veja os detalhes em [Mensagens de erro](/referencia/erros).

<Warning>
  Comportamentos abusivos (polling agressivo, padrões anômalos de tráfego) podem resultar em **bloqueio temporário ou permanente do IP**.
</Warning>

## Cadastro de IP na whitelist

Para operar com limites adequados, informe ao time de suporte ([suporte@ar-online.com.br](mailto:suporte@ar-online.com.br)) os **IPs públicos** ou **ranges CIDR** de origem do seu tráfego.

<Tip>
  Em ambientes cloud (AWS, GCP, Azure), garanta um **IP fixo de saída** (por exemplo, NAT Gateway ou Elastic IP) ou informe o range CIDR correspondente.
</Tip>

## Boas práticas

* **Prefira [webhooks](/webhooks/visao-geral)** para monitorar status em tempo real, evitando polling recorrente.
* Implemente filas com **retry e backoff exponencial** ao receber respostas 429.
* Monitore e trate as respostas `HTTP 429` na sua integração.