# Rate Limits

To ensure fair use and platform stability, our API enforces rate limits on all clients. If you exceed the allowed number of requests, the API will respond with a `429 Too Many Requests` status code.

## Rate Limit Policy

- Each client is allowed up to **120 requests per minute** by default (subject to change per endpoint or client type).
- The rate limit is enforced using a rolling window, so bursts of requests may be temporarily allowed as long as the average stays within the limit.

## Rate Limit Headers

Every API response includes headers to help you monitor your current rate limit status:

- `X-Rate-Limit-Limit`: The maximum number of requests allowed in the current window (e.g., `120`).
- `X-Rate-Limit-Remaining`: The number of requests remaining in the current window.
- `X-Rate-Limit-Reset`: The number of seconds until the rate limit window resets.

Example headers:

```
X-Rate-Limit-Limit: 120
X-Rate-Limit-Remaining: 15
X-Rate-Limit-Reset: 30
```

## Best Practices

- Monitor the `X-Rate-Limit-Remaining` header to avoid hitting the limit.
- Implement exponential backoff or retry logic when receiving a `429 Too Many Requests` response.
- Distribute requests evenly over time to avoid bursts.

## Handling Rate Limit Errors

If you exceed the rate limit, the API will return:

- HTTP status: `429 Too Many Requests`
- Rate limit headers indicating when you can retry

Example error response:

```json
{
  "code": 1900,
  "message": "You have exceeded your API rate limit."
}
```