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

# Rate Limits

> Fixed-window rate limiting by tier

Gildea uses fixed-window rate limiting on both per-minute and monthly windows.

## Limits by tier

| Tier | Requests/min | Requests/month         |
| ---- | ------------ | ---------------------- |
| Free | 20           | 250                    |
| Pro  | 60           | 5,000                  |
| Team | Custom       | Custom (contact sales) |

Monthly limits use a rolling 30-day window.

## Rate limit headers

Every authenticated response includes rate limit headers (limit, remaining, and the
reset time in unix epoch seconds) for each window:

```
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 58
X-RateLimit-Reset-Minute: 1749945600
X-RateLimit-Limit-Monthly: 5000
X-RateLimit-Remaining-Monthly: 4847
X-RateLimit-Reset-Monthly: 1752537600
```

## When you're rate limited

If you exceed your limit, the API returns `429`, with the same `X-RateLimit-*`
headers above (so you can see which window was hit and when it resets), plus a
`Retry-After` header in seconds:

```
Retry-After: 47
```

The retry timing is also echoed into the body, so clients that only read JSON
don't have to inspect headers. `retry_after` is the seconds to wait; `reset` is the
unix epoch second when the exceeded window clears:

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: 60 requests per minute",
    "status": 429,
    "retry_after": 47,
    "reset": 1749945600
  }
}
```

`Retry-After` reflects the actual time to the window reset, not a fixed value: for
the per-minute window it ranges from 1-60s depending on when in the window you hit
the cap. (A `429` from the monthly window can have a much larger `Retry-After`; if
you're hitting the monthly cap, upgrading your tier is usually the fix.)

## Best practices

1. **Check remaining counts**: use the `X-RateLimit-Remaining-*` headers to throttle proactively
2. **Respect Retry-After**: wait the indicated time before retrying
3. **Use pagination**: fetch fewer, larger pages instead of many small requests
4. **Cache responses**: signal data doesn't change frequently