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

# Limites de requisição

> Entenda os limites de requisição (rate limit) aplicados aos planos da caBRAPI, os headers de controle e como tratar o erro 429.

## Visão geral

A **caBRAPI** aplica limites de requisição (*rate limit*) para garantir **estabilidade, segurança e desempenho** da plataforma para todos os clientes.

* Os limites são aplicados **por plano contratado** e medidos em **janela fixa de 1 minuto**.
* **Cada rota possui um contador independente** — o consumo de um endpoint não afeta o limite dos demais.
* O consumo é contado **por credencial de API** (sua `apiKey`) — cada integração mede o próprio uso.

## Limites por plano

> [card] Básico
>
> Até **60** requisições por minuto.

> [card] Profissional
>
> Até **120** requisições por minuto.

> [card] Hyper
>
> Até **1.600** requisições por minuto.

> [!NOTE]
>
> Caso o limite seja ultrapassado, novas requisições são **temporariamente bloqueadas**, retornando erro `429` até que a janela seja reiniciada.

***

## Headers de controle

Toda resposta que passa pela validação de autenticação e plano inclui headers que permitem acompanhar o consumo em tempo real (respostas antecipadas `401`, `403` ou `404` são encerradas antes da aplicação dos headers de *rate limit*):

| Header | Descrição |
| - | - |
| `X-RateLimit-Limit` | Número máximo de requisições permitidas na janela atual. |
| `X-RateLimit-Remaining` | Quantas requisições ainda restam na janela atual. |

Quando o limite é atingido, a resposta de erro também inclui:

| Header | Descrição |
| - | - |
| `Retry-After` | Tempo, em segundos, até a janela reiniciar e novas requisições serem aceitas. |

***

## Quando o limite é excedido

Ao ultrapassar o limite, a API responde **`429 Too Many Requests`** e recusa novas requisições até a janela reiniciar:

```json theme={null}
{
  "code": "RATE_LIMIT_EXCEEDED"
}
```

> [!NOTE]
>
> A resposta usa o mesmo campo `code` dos demais erros da API. Veja **Erros**.

> [!WARNING]
>
> O tempo de espera é informado no header **`Retry-After`** (em segundos), **não** no corpo da resposta.

***

## Boas práticas

* **Monitore** o header `X-RateLimit-Remaining` para se autorregular antes de atingir o limite.
* Ao receber um `429`, **respeite o `Retry-After`** e só tente novamente após o tempo indicado.
* Implemente **retentativa com backoff exponencial** para lidar com picos de tráfego.
* Evite **polling agressivo**: consulte dados em intervalos maiores ou use **webhooks** para receber eventos em tempo real.

> [!TIP]
>
> Se o seu fluxo demanda mais requisições, avalie o **[upgrade de plano](https://cabrapi.com.br)** — o upgrade eleva o limite imediatamente.

***

## Paginação

Nos endpoints de listagem, use os parâmetros `page` e `limit` para controlar o volume de dados por resposta.

* `page`: inteiro maior ou igual a `1`
* `limit`: inteiro entre `1` e `100`

Quando esses parâmetros forem inválidos, a API retorna:

* `400 INVALID_PAGINATION` — quando `page` e `cursor` são enviados juntos
* `400 INVALID_PAGINATION_LIMIT`
* `400 INVALID_PAGINATION_PAGE`
* `400 INVALID_PAGINATION_CURSOR` — quando `cursor` é inválido ou malformado

### Paginação por cursor

Em listas grandes (mais de \~100 itens), prefira a paginação por **cursor**, que mantém a performance em qualquer volume de dados:

* Faça a primeira chamada **sem** `cursor` e use o campo `nextCursor` da resposta.
* Envie o `nextCursor` como `cursor` na próxima requisição para avançar na lista.
* O fim da lista é indicado por `nextCursor: null` + `hasMore: false` (a API responde `200` com array vazio).
* No modo offset, as respostas também incluem `nextCursor`/`hasMore`, permitindo migrar para cursor sem recomeçar do zero.

> [!TIP]
>
> Os limites podem ser ajustados conforme novos planos ou condições específicas da caBRAPI. Sempre consulte a **[documentação atualizada](https://docs.cabrapi.com.br)** para garantir informações corretas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.