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

# Rate Limits

> Per-tier rate limits and quota enforcement

## Limits by tier

| Tier     | Requests/min | Requests/month | Max perPage |
| -------- | ------------ | -------------- | ----------- |
| Free     | 10           | 100            | 10          |
| Starter  | 30           | 5,000          | 50          |
| Pro      | 60           | 25,000         | 500         |
| Business | 120          | 100,000        | 500         |

## Response headers

Metered `/v1` responses include rate-limit and quota headers. The public `/v1/health` endpoint is outside this middleware chain.

```
X-RateLimit-Limit: 60
X-Quota-Limit: 25000
X-Quota-Used: 142
X-Quota-Remaining: 24858
X-Quota-Overage-Limit: 50000
X-Request-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

| Header                  | Description                                                |
| ----------------------- | ---------------------------------------------------------- |
| `X-RateLimit-Limit`     | Max requests per minute for your tier                      |
| `X-Quota-Limit`         | Included quota for the active quota window                 |
| `X-Quota-Used`          | Requests used in the active quota window                   |
| `X-Quota-Remaining`     | Requests remaining in base quota (can be 0 during overage) |
| `X-Quota-Overage-Limit` | Hard limit including overage headroom (paid tiers only)    |
| `X-Request-Id`          | Unique request ID for log correlation                      |

`X-Quota-Overage-Limit` is only present for paid tiers. When `X-Quota-Used` exceeds `X-Quota-Limit`, you are in the overage zone: requests continue but incur per-request charges. Requests are blocked at the hard limit. See [Pricing](/borough/tiers-and-pricing#overage-billing) for overage rates.

Free anonymous quotas reset on the 1st of each calendar month. Paid customer quotas and overage counters follow the active Polar subscription billing period, so usage aligns with the billing invoice rather than a calendar-month boundary.

## Handling 429 responses

When you exceed the rate limit, the API returns a `429` status with a `Retry-After` header:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit of 60 requests per minute exceeded. Retry after 60 seconds.",
    "status": 429,
    "retryAfter": 60
  }
}
```

The wait time (in seconds) is exposed both in the `Retry-After` response header and as `error.retryAfter` in the JSON body. The SDK reads it automatically.

**Best practices:**

1. Read the `Retry-After` header and wait before retrying
2. Implement exponential backoff for repeated 429s
3. Use the SDK, which handles retries automatically

## Quota exceeded

Paid tiers have overage headroom: requests continue past the base quota and are billed at your tier's overage rate, up to the overage cap. Once the hard limit is reached:

```json theme={null}
{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota of 5000 requests plus overage cap exceeded. Resets at the end of the current billing period (2026-06-02T12:00:00.000Z).",
    "status": 429
  }
}
```

Free-tier users are blocked at 100 requests with no overage. The response also carries a `quotaContext` block (and `X-Quota-Tier` / `X-Quota-Upgrade-URL` headers) so you can prompt an upgrade at the moment you hit the limit:

```json theme={null}
{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly quota of 100 requests exceeded. Resets on the 1st of next month.",
    "status": 429,
    "quotaContext": {
      "currentTier": "FREE",
      "currentQuota": 100,
      "nextTier": "STARTER",
      "nextTierQuota": 5000,
      "upgradeUrl": "https://buy.polar.sh/..."
    }
  }
}
```

`nextTier` and `upgradeUrl` are `null` once you are on the top tier (Business).

## Checking your usage

Read the `X-Quota-*` response headers on any API response, or call `GET /v1/usage` for a full breakdown without spending a request:

```json theme={null}
{
  "data": {
    "tier": "STARTER",
    "quota": 5000,
    "used": 1234,
    "remaining": 3766,
    "overageLimit": 15000,
    "percentUsed": 25,
    "periodStart": "2026-07-01T00:00:00.000Z",
    "periodEnd": "2026-08-01T00:00:00.000Z"
  },
  "meta": { "dataAge": null, "source": "live" }
}
```

`GET /v1/usage` is authenticated and rate-limited but does **not** count against your monthly quota. The full machine-readable API spec is served at [`GET /v1/openapi.json`](https://borough.qwady.app/v1/openapi.json) for import into Postman, Bruno, or code generators.