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

# Rate limits

> Per-key request limits, rate-limit headers, and how to handle 429 responses.

Limits apply **per API key**, over a fixed 60-second window. Every endpoint belongs to one of two tiers:

| Tier | Limit | Endpoints |
| - | - | - |
| `default` | 120 requests per minute | Reads, including read-only lookups that are sent as `POST` |
| `write` | 60 requests per minute | Endpoints that create or change data, typically `POST` and `PUT` requests |

Each endpoint's reference page shows its tier.

## Headers

* Authenticated responses carry `X-RateLimit-Limit`, the request limit for that endpoint's tier.
* A `429` response carries `Retry-After`, the number of seconds to wait before retrying.

`GET /health` and `GET /docs` without a key have no per-key limit, so they don't send `X-RateLimit-Limit`.

## Handling 429

A request over the limit returns `429` with error type `rate_limit_error`:

```json theme={null}
{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded",
    "request_id": "req_…"
  }
}
```

Wait for the number of seconds in `Retry-After`, then retry. Spread bulk work out instead of bursting. For example, a single `submit-bulk` call carries up to 100 candidates.

<Note>
  A separate per-IP throttle runs at the network edge, and Paraform may apply additional per-endpoint limits. Any `429` can come from either, so always honor `Retry-After` rather than counting requests yourself.
</Note>


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