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

# Rate Limiting

> Understand API rate limits and how to handle them

The Poelis Public API implements rate limiting to ensure fair usage and system stability. All rate limits are applied per organization.

## Rate Limit Headers

Every API response includes rate limit information in the response headers:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995200
```

* **X-RateLimit-Limit**: Maximum number of requests allowed in the current window
* **X-RateLimit-Remaining**: Number of requests remaining in the current window
* **X-RateLimit-Reset**: Unix timestamp (seconds) when the window resets, as a string

## Default Limits

* **Requests per minute**: 60 requests per organization
* **Burst capacity**: 10 additional requests beyond the base limit

These limits may vary based on your organization's plan. Contact support for higher limits.

## Handling Rate Limits

When the limit is exceeded (429):

**Status:** 429 Too Many Requests

**Body (JSON):**

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests"
}
```

**Headers:**

* `Retry-After`: Seconds to wait before retrying (e.g. `"60"`)
* `X-RateLimit-Limit`: Limit value (e.g. `"120"` or `"60"`)
* `X-RateLimit-Remaining`: `"0"` when exceeded
* `X-RateLimit-Reset`: Unix timestamp (seconds) when the window resets, as a string

## Best Practices

<CardGroup cols={2}>
  <Card title="Monitor Headers" icon="chart-line">
    Always check `X-RateLimit-Remaining` to avoid hitting limits
  </Card>

  <Card title="Implement Caching" icon="database">
    Cache responses when possible to reduce API calls
  </Card>

  <Card title="Batch Requests" icon="layer-group">
    Use pagination efficiently to minimize requests
  </Card>

  <Card title="Handle 429 Gracefully" icon="shield-check">
    Implement exponential backoff for rate limit errors
  </Card>
</CardGroup>

## Requesting Higher Limits

If you need higher rate limits for your use case:

1. Contact [support@poelis.com ↗︎](mailto:support@poelis.com)
2. Describe your use case and expected request volume
3. We'll work with you to determine appropriate limits