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

# Rate Limiting

> Understand API rate limits, HTTP headers, and how to handle 429 errors.

Simiz uses rate limiting to protect the API, ensure stability, and distribute resources fairly across all customers.

## How it works

<Frame caption="Requests drain a token bucket. While capacity remains the API returns 200; once the burst window is exhausted it returns 429 with a Retry-After header.">
  <img src="/images/rate-limiting.svg" alt="Flow diagram: incoming requests drain a token bucket with an exhaustion threshold; under the limit returns 200 OK, over the limit returns 429 Too Many Requests with a Retry-After header." />
</Frame>

Each API key has a daily request limit and a burst rate (max requests per second) based on your plan. Higher plans offer increased limits.

<Tip>
  The **sandbox environment** has relaxed rate limits — test as much as you want during development.
</Tip>

## Rate limit headers

Every API response includes headers to help you monitor your usage:

| Header                  | Description                                   |
| ----------------------- | --------------------------------------------- |
| `X-RateLimit-Limit`     | Max requests allowed in the time window       |
| `X-RateLimit-Remaining` | Requests remaining in the current window      |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets         |
| `Retry-After`           | Seconds to wait before retrying (on 429 only) |

## Handling rate limit errors

When you exceed the limit, the API returns **HTTP 429 Too Many Requests**:

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry later.",
    "http_status": 429,
    "retry_after": 60
  }
}
```

### Retry with exponential backoff

```bash
# Wait and retry with increasing delays
# Attempt 1: wait 1s → Attempt 2: wait 2s → Attempt 3: wait 4s
```

## Best practices

<CardGroup cols={2}>
  <Card title="Cache responses" icon="database">
    Cache data that doesn't change often to reduce API calls.
  </Card>

  <Card title="Exponential backoff" icon="arrows-rotate">
    On rate limits, wait with increasing delays between retries.
  </Card>

  <Card title="Check headers" icon="eye">
    Monitor `X-RateLimit-Remaining` to anticipate limits before hitting them.
  </Card>

  <Card title="Spread calls" icon="clock">
    Distribute API calls over time instead of sending bursts.
  </Card>
</CardGroup>

<Note>
  Need higher limits? [Contact our sales team](mailto:sales@simiz.io) for plans with increased rate limits.
</Note>