Rate limits and quotas

MedFlow protects the platform and your tenant with two kinds of ceilings: rate limits on how often you call, and quotas on how much concurrent work you can have in flight. Both are enforced per API key and per tenant.

Every response carries your current limit state in headers, so you can pace clients without guessing.

Rate limit headers

Every API response includes:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1784764800

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the current window
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Unix time (seconds) when the window resets

When you exceed a limit

A rate-limited request returns 429 with a Retry-After header (seconds):

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "error": "Rate limit exceeded",
  "code": "rate_limited",
  "requestId": "<string>"
}

Back off and retry after Retry-After with jitter, and no faster than the header asks.

Default limits

These are starting points. Your tenant’s active limits are always the ones returned in the headers above, and can be raised by agreement.

Limit	Default	Scope
Request rate	600 requests / minute	Per API key
Concurrent runs	50 in flight	Per tenant
Search / count	60 requests / minute	Per API key
Inbound ingest payload	5 MB per request	Per request
Webhook delivery	120 events / minute	Per webhook endpoint

Quotas and backpressure

Concurrent runs cap how many runs can be running or scheduled at once. Beyond the cap, new runs stay queued and start as capacity frees up, rather than being rejected. Watch the queue with aggregate status.
Large cohorts started by a search trigger are admitted in batches under the concurrent-run quota, so a 10,000-patient cohort does not start 10,000 runs at once.
Data larger than the payload limit should be split into multiple deliveries or sent through a bulk FHIR sync (data source).

Handling limits well

Read X-RateLimit-Remaining and slow down before you hit 0.
Use one idempotency key per real-world event so a retry after 429 does not create a duplicate run.
Prefer webhooks over tight polling. When you must poll, follow the polling guidance.

To request higher limits, use the contact form.