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

# Rate limits

> Each API key gets 300 requests per 60-second window, shared between the REST API and MCP; read the X-RateLimit headers and honor Retry-After on 429.

Rate limits keep one busy integration from slowing down everyone else. They apply per key, so two integrations with two keys never compete for the same allowance.

## Limits

| What's counted | Limit | Window | Counted per |
| - | - | - | - |
| Authenticated requests (REST API and MCP combined) | 300 | 60 seconds | API key |

The limits are the same on every plan.

* **Every authenticated request counts**, including `/me`, requests that end in `304 Not Modified`, and requests refused with `403` for a missing scope.
* **REST and MCP share the allowance.** Each MCP call made with a key counts against the same 300 requests as that key's REST calls.
* **Each window resets on the whole minute.**

## Headers

Successful responses (`200` and `304`), `403 insufficient_scope` and key-level `429` responses carry:

| Header | Meaning | Example |
| - | - | - |
| `X-RateLimit-Limit` | Requests allowed per window for this key | `300` |
| `X-RateLimit-Remaining` | Requests left in the current window | `287` |
| `X-RateLimit-Reset` | Seconds until the window resets | `42` |
| `Retry-After` | On `429` only: seconds to wait before retrying | `42` |

`X-RateLimit-Reset` is a number of seconds, not a timestamp.

## When you hit the limit

A key that runs out of requests gets `429 Too Many Requests`:

```http theme={"system"}
HTTP/2 429
content-type: application/problem+json; charset=utf-8
retry-after: 18
x-ratelimit-limit: 300
x-ratelimit-remaining: 0
x-ratelimit-reset: 18
x-request-id: 0b6f2a9e-3c1d-4e8f-9a7b-5d2c1e0f3a4b
```

```json theme={"system"}
{
  "type": "/api/v1/problems/rate_limited",
  "title": "Rate limited",
  "status": 429,
  "instance": "urn:request:0b6f2a9e-3c1d-4e8f-9a7b-5d2c1e0f3a4b"
}
```

Wait `Retry-After` seconds, then retry the same request. A `429` is answered before anything runs, so retrying it is safe for every endpoint, the facts writes included. For retries after a timeout or a `5xx`, see [Retry writes safely](https://docs.usequotable.com/api-reference/errors.md#retry-writes-safely).

### Failed authentication

Repeated failed authentications from one network are throttled with `429` and `Retry-After`. Fix the key rather than retrying: a `401` won't succeed on its own.

## Handle 429 in code

```javascript JavaScript theme={"system"}
const BASE = "https://app.usequotable.com/api/v1";

export async function quotable(path, { maxRetries = 3 } = {}) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(`${BASE}${path}`, {
      headers: { Authorization: `Bearer ${process.env.QUOTABLE_API_KEY}` },
    });
    if (res.status !== 429 || attempt >= maxRetries) {
      if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
      return res.json();
    }
    const wait = Number(res.headers.get("retry-after") ?? "1");
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
}
```

```python Python theme={"system"}
import os
import time
import requests

BASE = "https://app.usequotable.com/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['QUOTABLE_API_KEY']}"

def quotable(path, params=None, max_retries=3):
    for attempt in range(max_retries + 1):
        res = session.get(f"{BASE}{path}", params=params, timeout=30)
        if res.status_code != 429 or attempt == max_retries:
            res.raise_for_status()
            return res.json()
        time.sleep(int(res.headers.get("Retry-After", "1")))
```

## Stay under the limit

* **Pace bulk jobs.** If `X-RateLimit-Remaining` gets low, sleep for `X-RateLimit-Reset` seconds before the next call instead of waiting for a `429`.
* **Use the largest page.** Pass `limit=100` when you export whole lists. That's half the requests of the default page size.
* **Don't poll for changes.** Subscribe to [webhooks](https://docs.usequotable.com/webhooks/overview.md) and fetch only when something happened.
* **Revalidate instead of re-downloading.** Send `If-None-Match` with the last `ETag`. A `304` still counts as a request but returns no body. See [Caching and request IDs](https://docs.usequotable.com/api-reference/caching-and-request-ids.md).
* **One key per integration.** Each key has its own 300-request allowance.

## Next steps

> [card] [Pagination](https://docs.usequotable.com/api-reference/pagination.md)
>
> Page through large lists efficiently.

> [card] [Errors](https://docs.usequotable.com/api-reference/errors.md)
>
> The full list of problem types and how to handle each.


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