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

# Límites de solicitud

> Comprende los límites de solicitud (rate limit) aplicados a los planes de caBRAPI, los headers de control y cómo tratar el error 429.

## Descripción general

La **caBRAPI** aplica límites de solicitud (*rate limit*) para garantizar **estabilidad, seguridad y rendimiento** de la plataforma para todos los clientes.

* Los límites se aplican **por plan contratado** y se miden en **ventana fija de 1 minuto**.
* **Cada ruta tiene un contador independiente** — el consumo de un endpoint no afecta el límite de los demás.
* El consumo se cuenta **por credencial de API** (tu `apiKey`) — cada integración mide su propio uso.

## Límites por plan

> [card] Básico
>
> Hasta **60** solicitudes por minuto.

> [card] Profesional
>
> Hasta **120** solicitudes por minuto.

> [card] Hyper
>
> Hasta **1.600** solicitudes por minuto.

> [!NOTE]
>
> Si se supera el límite, las nuevas solicitudes se **bloquean temporalmente**, devolviendo el error `429` hasta que la ventana se reinicie.

***

## Headers de control

Toda respuesta que pasa la validación de autenticación y plan incluye headers que permiten acompañar el consumo en tiempo real (las respuestas anticipadas `401`, `403` o `404` se interrumpen antes de aplicar los headers de *rate limit*):

| Header | Descripción |
| - | - |
| `X-RateLimit-Limit` | Número máximo de solicitudes permitidas en la ventana actual. |
| `X-RateLimit-Remaining` | Cuántas solicitudes aún restan en la ventana actual. |

Cuando se alcanza el límite, la respuesta de error también incluye:

| Header | Descripción |
| - | - |
| `Retry-After` | Tiempo, en segundos, hasta que la ventana se reinicie y se acepten nuevas solicitudes. |

***

## Cuando se excede el límite

Al superar el límite, la API responde **`429 Too Many Requests`** y rechaza nuevas solicitudes hasta que la ventana se reinicie:

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

> [!NOTE]
>
> La respuesta usa el mismo campo `code` que los demás errores de la API. Consulta **Errores**.

> [!WARNING]
>
> El tiempo de espera se informa en el header **`Retry-After`** (en segundos), **no** en el cuerpo de la respuesta.

***

## Mejores prácticas

* **Monitorea** el header `X-RateLimit-Remaining` para autorregularse antes de alcanzar el límite.
* Al recibir un `429`, **respeta el `Retry-After`** y vuelve a intentarlo solo después del tiempo indicado.
* Implementa **reintento con backoff exponencial** para manejar picos de tráfico.
* Evita el **polling agresivo**: consulta datos a intervalos mayores o usa **webhooks** para recibir eventos en tiempo real.

> [!TIP]
>
> Si tu flujo demanda más solicitudes, evalúa el **[upgrade de plan](https://cabrapi.com.br)** — el upgrade eleva el límite de inmediato.

***

## Paginación

En los endpoints de listado, usa los parámetros `page` y `limit` para controlar el volumen de datos por respuesta.

* `page`: entero mayor o igual a `1`
* `limit`: entero entre `1` y `100`

Cuando estos parámetros sean inválidos, la API devuelve:

* `400 INVALID_PAGINATION` — cuando se combinan `page` y `cursor`
* `400 INVALID_PAGINATION_LIMIT`
* `400 INVALID_PAGINATION_PAGE`
* `400 INVALID_PAGINATION_CURSOR` — cuando `cursor` es inválido o malformado

### Paginación por cursor

En listas grandes (más de \~100 elementos), prefiere la paginación por **cursor**, que mantiene el rendimiento en cualquier volumen de datos:

* Realiza la primera llamada **sin** `cursor` y usa el campo `nextCursor` de la respuesta.
* Envía el `nextCursor` como `cursor` en la siguiente solicitud para avanzar en la lista.
* El fin de la lista se indica con `nextCursor: null` + `hasMore: false` (la API responde `200` con array vacío).
* En el modo offset, las respuestas también incluyen `nextCursor`/`hasMore`, permitiendo migrar a cursor sin empezar de cero.

> [!TIP]
>
> Los límites pueden ajustarse según nuevos planes o condiciones específicas de caBRAPI. Siempre consulta la **[documentación actualizada](https://docs.cabrapi.com.br)** para garantizar información correcta.


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