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

# Rate limits

> Per merchant quotas, rate limit headers, and how to handle HTTP 429.

Rate limiting keeps the Escrow API stable. There is a limited number of requests you can make per time window for each endpoint family. Going beyond that limit returns **HTTP 429** with `error.code` `RATE_LIMITED`.

Limits apply **per merchant**, with a **separate quota for test and live** (your `sk_test_` / `sk_live_` key). Hitting the limit on one family does not freeze other families.

## Rate limit headers

On success and on 429, read these response headers:

| Header | Meaning |
| - | - |
| `x-ratelimit-limit` | Max requests permitted in the current window for this family. |
| `x-ratelimit-remaining` | Requests left in the current window. |
| `x-ratelimit-reset` | Seconds until the current window ends, when you can retry. |

On 429 you also get `Retry-After` (seconds), matching `x-ratelimit-reset`.

## Error body

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "details": {
      "nextStep": "Wait 42 seconds and try again",
      "resetInSeconds": 42,
      "limit": 100,
      "family": "standard",
      "endpoint": "Standard secret key routes"
    }
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}
```

## Standard limits

Most secret key routes share the standard family.

| Mode | Limit |
| - | - |
| Test (`sk_test_`) | **100** requests per 60 seconds |
| Live (`sk_live_`) | **300** requests per 60 seconds |

Test mode is for development and integration testing, not load testing.

## Extended limits

These foundational routes have their own higher buckets in **live** mode so critical flows keep moving. In **test** mode they use the standard limit above.

| Endpoint family | Live limit (per 60 seconds) |
| - | - |
| `GET /identity/banks` | **600** |
| `POST /identity/bank-accounts/verify` | **300** |
| `POST /checkout/sessions` | **200** |
| Escrow writes (`POST /escrows`, release, refund, cancel, disputes, resolve) | **200** |
| `POST /withdrawals` | **150** |

## Handling a 429

1. Read `x-ratelimit-reset` (seconds).
2. Pause requests to **that** endpoint family until the window ends.
3. If you see sustained 429s across many families, pause and investigate. An unchecked poll loop is usually the cause.

## Staying within limits

* Prefer [webhooks](/guides/webhooks) over polling `GET /escrows/{id}` after checkout or payout.
* Cache stable lookups such as `GET /identity/banks`.
* Page through lists (default 20, max 100). See [Pagination](/guides/pagination).
* Use [idempotency keys](/guides/idempotency) on money moving `POST`s so timeouts do not double release or double pay.

If you need higher sustained limits for production traffic, contact Demat support with the endpoint family, expected peak rate, and a short description of your integration.


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