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

# Request limits

> Understand the request limits (rate limit) applied to caBRAPI plans, the control headers and how to handle the 429 error.

## Overview

**caBRAPI** applies request limits (*rate limit*) to guarantee **stability, security and performance** of the platform for all customers.

* Limits are applied **per contracted plan** and measured in a **fixed 1-minute window**.
* **Each route has an independent counter** — consuming one endpoint does not affect the limit of the others.
* Usage is counted **per API credential** (your `apiKey`) — each integration measures its own usage.

## Limits per plan

> [card] Basic
>
> Up to **60** requests per minute.

> [card] Professional
>
> Up to **120** requests per minute.

> [card] Hyper
>
> Up to **1,600** requests per minute.

> [!NOTE]
>
> If the limit is exceeded, new requests are **temporarily blocked**, returning a `429` error until the window restarts.

***

## Control headers

Every response that passes authentication and plan validation includes headers that allow tracking consumption in real time (early `401`, `403`, or `404` responses abort before rate-limit headers are applied):

| Header | Description |
| - | - |
| `X-RateLimit-Limit` | Maximum number of requests allowed in the current window. |
| `X-RateLimit-Remaining` | How many requests are still remaining in the current window. |

When the limit is reached, the error response also includes:

| Header | Description |
| - | - |
| `Retry-After` | Time, in seconds, until the window restarts and new requests are accepted. |

***

## When the limit is exceeded

When exceeding the limit, the API responds with **`429 Too Many Requests`** and refuses new requests until the window restarts:

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

> [!NOTE]
>
> The response uses the same `code` field as the other API errors. See **Errors**.

> [!WARNING]
>
> The wait time is informed in the **`Retry-After`** header (in seconds), **not** in the response body.

***

## Best practices

* **Monitor** the `X-RateLimit-Remaining` header to self-regulate before reaching the limit.
* When receiving a `429`, **respect the `Retry-After`** and only try again after the indicated time.
* Implement **retry with exponential backoff** to handle traffic peaks.
* Avoid **aggressive polling**: query data at larger intervals or use **webhooks** to receive events in real time.

> [!TIP]
>
> If your flow demands more requests, consider a **[plan upgrade](https://cabrapi.com.br)** — the upgrade raises the limit immediately.

***

## Pagination

In listing endpoints, use the `page` and `limit` parameters to control the volume of data per response.

* `page`: integer greater than or equal to `1`
* `limit`: integer between `1` and `100`

When these parameters are invalid, the API returns:

* `400 INVALID_PAGINATION` — when `page` and `cursor` are combined
* `400 INVALID_PAGINATION_LIMIT`
* `400 INVALID_PAGINATION_PAGE`
* `400 INVALID_PAGINATION_CURSOR` — when `cursor` is invalid or malformed

### Cursor pagination

In large lists (more than \~100 items), prefer **cursor** pagination, which keeps performance at any data volume:

* Make the first call **without** `cursor` and use the `nextCursor` field from the response.
* Send the `nextCursor` as `cursor` in the next request to advance in the list.
* The end of the list is indicated by `nextCursor: null` + `hasMore: false` (the API responds `200` with an empty array).
* In offset mode, responses also include `nextCursor`/`hasMore`, allowing migration to cursor without starting from scratch.

> [!TIP]
>
> Limits may be adjusted according to new plans or specific conditions of caBRAPI. Always check the **[updated documentation](https://docs.cabrapi.com.br)** to ensure correct information.


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