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

# Rate limits

> Request limits, how they are scoped, and how to handle a 429

The Dolfin API is rate limited. Requests over the limit are rejected with **HTTP 429 Too Many
Requests** and no work is performed — a rejected request never partially applies.

## The limit that applies to every endpoint

| Limit            | Window     | Scoped by             |
| ---------------- | ---------- | --------------------- |
| **120 requests** | 60 seconds | **Source IP address** |

This covers every endpoint, on every path, whether authenticated or public.

Sustained abuse is treated more harshly: an IP exceeding **600 requests in 60 seconds** is blocked
for **10 minutes**, and every request during that period returns 429.

<Warning>
  Limits are scoped by **source IP, not by API key or organisation**. If you call Dolfin from a server
  with a single egress IP, every organisation you serve shares one 120 req/min budget. Plan capacity
  against your total request volume across all tenants, not per tenant.

  If you run behind NAT or a shared gateway, unrelated traffic from the same address counts toward
  your budget too. A dedicated egress IP is the reliable way to get a predictable budget.
</Warning>

## Additional limits on specific endpoints

Some endpoints carry a second, narrower limit on top of the 120 req/min above. Where both apply,
whichever is reached first rejects the request.

| Endpoints                                                                                      | Limit        | Window     | Scoped by                 |
| ---------------------------------------------------------------------------------------------- | ------------ | ---------- | ------------------------- |
| `POST /v1/auth/codes`, `POST /v1/auth/exchange`, registration, invite acceptance               | 10 requests  | 60 seconds | shared across all callers |
| Public payment and approval pages (`/i/{token}`, checkout session, public bill approve/reject) | 60 requests  | 60 seconds | per token                 |
| `POST /v1/mcp`                                                                                 | 120 requests | 60 seconds | per API key               |
| Inbound webhook receivers (Stripe, Postmark, Yapily)                                           | 600 requests | 60 seconds | per source IP             |

<Note>
  The authentication limit is deliberately strict and is **shared across all callers**, not per
  client. Exchange your credentials for a token once and reuse it for the token's lifetime rather
  than authenticating per request — see [Authentication](/guides/authentication).
</Note>

## Handling a 429

A rejected request returns status `429` with an empty body.

<Warning>
  429 responses do **not** include a `Retry-After` header, and unlike other Dolfin errors they do not
  carry a machine-readable `code` field. Switch on the HTTP status code alone.
</Warning>

Because every window is a **fixed 60 seconds**, you do not need a header to recover correctly:

* **Throttled at 120 req/min** — wait until the current minute elapses. Waiting a full 60 seconds
  always clears it.
* **Blocked after sustained abuse** — wait **10 minutes**. Retrying sooner will not succeed and
  extends the pattern that triggered the block.

Recommended client behaviour:

```
on 429:
  wait 60s, then retry
  on a second consecutive 429:
    back off exponentially (60s, 120s, 240s …) with jitter, capped at 10 minutes
```

Jitter matters: if you batch work across many tenants, a fixed retry delay makes every worker
retry in the same instant and re-trip the limit.

## Staying under the limits

* **Use pagination rather than polling.** List endpoints return a cursor; page through results
  instead of re-requesting the collection.
* **Use [webhooks](/guides/webhooks) instead of polling for state changes.** Waiting for
  `bill.approved` costs nothing; polling a bill every few seconds until it changes is the most
  common way integrations hit the limit.
* **Batch overnight work with a delay between requests.** 120 req/min is two per second sustained;
  a bulk import should pace itself rather than burst.
* **Reuse tokens.** Re-authenticating per request will hit the auth limit long before the general
  one.

## Requesting a higher limit

If your integration legitimately needs more than 120 requests per minute, contact your Dolfin
representative with your expected peak volume and the egress IPs you call from.