Rate limits

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:

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

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

429 RATE_LIMITED

{
  "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.

Node.js

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.

Get started

Concepts

Guides

MCP reference

Reference

The limits

Headers

When you hit one

When the limiter is down

​The limits

​Headers

​When you hit one

​When the limiter is down

The limits

Headers

When you hit one

When the limiter is down