***

title: Rate Limiting
subtitle: Request limits, headers, and handling guidance
slug: api-guides/rate-limiting
---------------------

For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.prolifi.io/api-guides/llms.txt. For full documentation content, see https://docs.prolifi.io/api-guides/llms-full.txt.

## Limits

The Prolifi Public API enforces rate limits per API key. Each API key has an independent rate limit counter.

| Parameter                   | Default  |
| --------------------------- | -------- |
| Maximum requests per window | 1,000    |
| Window duration             | 1 minute |

<Note>
  Rate limits are applied per API key, not per merchant. If you use multiple API keys, each key has its own independent limit.
</Note>

## Rate limit headers

Every response includes rate limit headers:

| Header                  | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum number of requests allowed in the current window |
| `X-RateLimit-Remaining` | Number of requests remaining in the current window       |

When the rate limit is exceeded, a `429` response is returned with an additional header:

| Header        | Description                               |
| ------------- | ----------------------------------------- |
| `Retry-After` | Number of seconds to wait before retrying |

## Exceeded limit response

```json
{
  "error": {
    "type": "rate_limit_error",
    "message": "Too many requests. Please retry after the rate limit resets."
  }
}
```

## Handling rate limits

* **Monitor the `X-RateLimit-Remaining` header** to anticipate when you are approaching the limit.
* **On `429`, wait for the `Retry-After` duration** before retrying. Do not retry immediately.
* **Implement exponential backoff** for bursts of rate-limited requests.
* **Batch usage events** using the `POST /events/batch` endpoint to reduce the number of individual requests.