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

# Rate Limits

> Request limits, rate-limiting buckets, and handling 429 responses

The Nmbr API limits how many requests you can make per minute. Every response tells you how much
of your limit is left, and a request that goes over the limit returns `429 Too Many Requests`
without being processed.

The same limits apply in sandbox and production.

## Limits

| Rate-limiting bucket | Limit                     | Applies to                                                                                                               |
| -------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| API requests         | 1,000 requests per minute | All endpoints unless documented below                                                                                    |
| Reveal               | 25 requests per minute    | The `/reveal` endpoints, such as `GET /employees/<employee_id>/reveal` and `GET /bank_accounts/<bank_account_id>/reveal` |

Both limits cover the requests you make with your own access tokens. Requests made by the Nmbr
Component are counted separately and do not count toward either limit.

## How rate-limiting buckets work

A rate-limiting bucket is a counter. Each one counts your requests in a one-minute window. The
window opens on your first request and the counter resets 60 seconds later. It is not aligned to the
clock minute.

**Your allowance is per authenticated entity.** Requests to partner endpoints count against your
partner, and requests to company endpoints count against the company in the access token you used.
Each company you serve gets its own 1,000 requests per minute, so a busy company can't exhaust
another company's allowance.

**The reveal bucket is additional.** A call to a `/reveal` endpoint counts against both the reveal
bucket and the API requests bucket. Reveal endpoints return sensitive values such as a full Social
Insurance Number, so they carry a tighter limit of their own. Read one record at a time and cache
what you need rather than revealing a list of employees in a loop.

**Nmbr Component traffic does not count toward your API rate limits.** Requests the Component makes
for your users go into a rate-limiting bucket of their own, separate from the buckets above. A user
working in the Component never consumes the allowance your own integration is spending.

## Rate limit headers

Every response carries your standing in the rate-limiting bucket:

| Header                  | Value                                                |
| ----------------------- | ---------------------------------------------------- |
| `X-RateLimit-Limit`     | The maximum number of requests allowed in the window |
| `X-RateLimit-Remaining` | The number of requests left in the current window    |

A `429` response adds two more:

| Header              | Value                                         |
| ------------------- | --------------------------------------------- |
| `Retry-After`       | The number of seconds to wait before retrying |
| `X-RateLimit-Reset` | The Unix timestamp when the window resets     |

When more than one limit applies to an endpoint, the headers describe the rate-limiting bucket you
are closest to exhausting.

## Over the limit

**Response**

```http theme={null}
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
Retry-After: 34
X-RateLimit-Reset: 1753912800
```

```json theme={null}
{
  "message": "Too Many Attempts."
}
```

Wait `Retry-After` seconds, then retry. A `429` means the request never reached the API, so nothing
was created, updated, or deleted. If the request carried an `X-Idempotency-Key`, the key was not
consumed and you can retry with the same one. See [Idempotency](/api/overview/idempotency).

## Staying under the limit

* Use the [bulk and batch endpoints](/api/bulk-and-batch-operations/bulk-and-batch-operations) to
  write many entities in one request instead of one request per entity.
* Use [`expand`](/api/overview/response-structure#expanding-resources) to pull related resources
  into a single response instead of following each stub with another request.
* Back off using `Retry-After` instead of retrying immediately. Retrying in a tight loop keeps you
  over the limit and delays your own recovery.