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

# Rate Limits

> Per-minute and daily limits, response headers, and retry guidance

Every API key has per-minute request limits that vary by endpoint, and a daily limit on calls and on rows returned.

## Daily limits

Keys without a plan of their own are on the free limits:

| Limit | Free |
| - | - |
| Calls a minute | **30** |
| Calls a day | **300** |
| Rows returned a day | **3,000** |

Days run from 00:00 UTC. A key that is shared by several people (the console key) is counted per network address, and all of its callers also share one daily total. The MCP server counts the same way, per signed-in user or per key.

When a daily limit is reached the API answers `429` with `"error": "Usage limit reached"`, a `reason` (`minute`, `day`, `rows` or `shared`) and a `Retry-After` header. Keys for production integrations have higher limits: write to [api@courtrules.app](mailto:api@courtrules.app).

## Limits by endpoint

| Endpoint | Limit | Rationale |
| - | - | - |
| `POST /api/v1/classify` | **5 RPM** | Analyzes PDFs; 10-30s per request |
| `POST /api/v1/check` | **60 RPM** | Deterministic, sub-millisecond |
| `GET /api/v1/courts`, `/judges`, `/rules` | **300 RPM** | Read-only lookups |

RPM = requests per minute, per API key. These endpoint limits use a sliding window. The daily limits above, and the 30 calls a minute on the free limits, count in fixed windows: the clock minute and the UTC day.

## Response headers

Responses from the endpoint limits include rate limit headers. A response refused by the daily limits carries `Retry-After` and a `reason` instead:

| Header | Description | Example |
| - | - | - |
| `X-RateLimit-Limit` | Maximum requests allowed in the window | `5` |
| `X-RateLimit-Remaining` | Requests remaining in the current window | `3` |
| `X-RateLimit-Reset` | Unix epoch (seconds) when the window resets | `1709913600` |

## 429 response

When the limit is exceeded, the API returns `429 Too Many Requests`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "Rate limit exceeded",
  "suggestion": "Wait 30 seconds before retrying. See rate limit headers for usage details.",
  "docs_url": "https://docs.courtrules.app/api-reference/rate-limits",
  "contact": "api@courtrules.app"
}
```

The response also includes a `Retry-After` header with the number of seconds to wait.

## Retry guidance

1. **Read `Retry-After`** and wait at least that many seconds before retrying.
2. **Use exponential backoff** if you receive multiple 429s in a row: wait 1s, 2s, 4s, etc.
3. **Check `X-RateLimit-Remaining`** before sending requests to avoid hitting the limit in the first place.

## Common mistakes

**Tight-loop classify calls.** `/classify` is limited to 5 RPM because each request takes 10-30 seconds to analyze a PDF. If you need to process a batch, space requests at least 12 seconds apart or queue them server-side.

**Ignoring `Retry-After`.** Retrying immediately after a 429 wastes your remaining budget and delays recovery. Always respect the header value.

**Polling `/check` on every keystroke.** While `/check` has a generous 60 RPM limit, calling it on every form change in a UI can still exhaust it. Debounce to at most once per second.

## Need higher limits?

Contact [api@courtrules.app](mailto:api@courtrules.app) with your use case. We can increase limits for production integrations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.