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

# Rate Limits

> Generous request limits, the headers that report them, and how to handle 429s.

Spritz's rate limits aim to be very generous, and most integrations never come close to
them. If you expect high volume or run into a limit that gets in your way, reach out
and we'll work with you. Contact us through the
[Help Center](https://help.spritz.finance/en/).

## Prefer webhooks over polling

The most common reason to hit a rate limit is polling the API for status changes. You
usually don't need to. Spritz emits [webhooks](/guides/webhooks) for the events that
matter (payments, on-ramps, verification, and more), so you can react to changes as
they happen instead of polling in a loop.

## Reading the headers

Every response includes your current rate-limit status, so you can pace requests
without guessing:

| Header                  | Meaning                                                      |
| ----------------------- | ------------------------------------------------------------ |
| `X-RateLimit-Limit`     | The maximum number of requests allowed in the current window |
| `X-RateLimit-Remaining` | How many requests you have left in the current window        |
| `X-RateLimit-Reset`     | When the window resets, as an ISO 8601 timestamp             |

```http theme={null}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994
X-RateLimit-Reset: 2026-06-30T12:34:56.000Z
```

## When you exceed a limit

If you go over, the API responds with `429 Too Many Requests` and a `Retry-After`
header telling you how many seconds to wait. The body is a standard
[problem response](/guides/errors):

```json theme={null}
{
  "type": "urn:problem-type:rate-limit",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please retry after 30 seconds.",
  "retryAfter": 30,
  "limit": 1000,
  "remaining": 0,
  "resetAt": "2026-06-30T12:34:56.000Z"
}
```

Wait for the period in `Retry-After` before retrying, and back off exponentially if you
keep getting `429`s. If you're hitting limits during normal operation,
[get in touch](https://help.spritz.finance/en/), that's usually a sign we should raise
your limits.