Rate limits
Rate limits are per-client — keyed on your authenticated credential, so your quota follows you across NAT and proxies. Response headers tell you where you stand.
Tiers
Each client has a rate_limit_tier. The default tier suits most integrations; higher-volume partners are provisioned a higher tier.
| Tier | Default limit | Who |
|---|---|---|
default | 600 requests / minute | Standard integrations and every newly-issued sandbox key. |
high | 6,000 requests / minute | High-volume partners, provisioned by arrangement after review. |
unlimited | No limit (limiter bypassed) | Reserved for internal / first-party MedFlo use. Not offered to third-party integrations. |
Headers
Every response includes X-RateLimit-* headers so you can self-throttle before you're limited:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Your ceiling for the current window. |
X-RateLimit-Remaining | Requests left in the window. |
X-RateLimit-Reset | When the window resets. |
When you're over
An over-limit request returns 429 with error code rate_limited in the standard envelope. Back off and retry after the reset. Because the token endpoint is limited by IP (not client) to blunt credential stuffing, cache and reuse your token for its full lifetime rather than re-fetching per request.
Be a good citizen
Reuse tokens for their full hour, paginate with a reasonable
page_size, and prefer webhooks over polling for changes.