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

# Rate limits

> Per-credential bursts, per-clinic sustained rates and an hourly ceiling on patient records, with RateLimit headers on every answer.

Limits protect each clinic from a runaway client and patients from mass extraction. They are generous for normal use.

## The limits

| Limit | Counts | Window | Default |
| - | - | - | - |
| `burst` | Requests per **credential** | 10 s | 100 |
| `standard` | Requests per **clinic** to standard operations, all credentials together | 60 s | 600 |
| `heavy` | Requests per **clinic** to heavy operations (none in this version) | 60 s | 30 |
| `patient_records` | Patient records **returned** to one credential | 1 hour | 2,000 |
| Webhook tests | `POST /v1/webhooks/{id}/test` per webhook | 60 s | 5 |

* `standard` is shared by every key, app and assistant of the clinic: a loop in one integration can slow the others. Spread batch jobs out.
* `patient_records` counts what leaves Brelio: a list page of 100 patients counts 100. When it is reached, the clinic's owners are alerted.
* A clinic can have higher limits by agreement.

## Headers

Every answer to an authenticated call carries the IETF `RateLimit-Policy` and `RateLimit` headers:

```text theme={null}
RateLimit-Policy: "burst";q=100;w=10, "standard";q=600;w=60
RateLimit: "standard";r=599;t=52
```

* `RateLimit-Policy` lists the limits that apply: `q` is the quota, `w` the window in seconds.
* `RateLimit` reports the closest one: `r` requests remaining, `t` seconds until it resets.

## When you hit one

```text theme={null}
HTTP/1.1 429 Too Many Requests
RateLimit-Policy: "burst";q=100;w=10, "standard";q=600;w=60
RateLimit: "standard";r=0;t=43
Retry-After: 43
```

```json 429 RATE_LIMITED theme={null}
{
  "type": "https://api.brelio.app/problems/rate-limited",
  "title": "Too Many Requests",
  "status": 429,
  "code": "RATE_LIMITED",
  "detail": "The standard limit was reached.",
  "request_id": "a258784d-fd6b-4674-af1e-f653bf8ad727",
  "params": {},
  "hint": "Wait 43 s before retrying; spread calls or ask for a higher limit.",
  "retryAfterSeconds": 43
}
```

Wait `Retry-After` seconds (also in `retryAfterSeconds`) before the next call. Over MCP the same object comes back as the tool's error result.

```javascript Node.js theme={null}
async function call(url, init) {
  for (;;) {
    const response = await fetch(url, init)
    if (response.status !== 429) return response
    const seconds = Number(response.headers.get('retry-after') ?? '1')
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
  }
}
```

## When the limiter is down

If the limiter does not answer, request rates are let through, but operations on patient data are refused with `503 PLATFORM_LIMITS_UNAVAILABLE` and `Retry-After: 5`, so the patient-record ceiling is never skipped.


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