Rate limits

Limits keep the service responsive for every organization. When you reach one, the response is 429, and nothing is charged.

Limits

RateLimit headers

Responses that count toward a per-minute limit say where you stand, in the three headers of the IETF draft "RateLimit header fields for HTTP":

• Reads (GET and HEAD requests, and POST /v1/analyses/search) report the API key's read limit.
• POST /v1/analyses and POST /v1/batches report your organization's analysis call limit.
• Other requests, such as the token endpoint and DELETE, carry no RateLimit headers.

The headers come with 429 responses too, with RateLimit-Remaining: 0.

RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 20

Pace your requests with RateLimit-Remaining and RateLimit-Reset; after a 429, wait for Retry-After.

Analysis calls

The per-minute limit counts the calls your organization made in the last 60 seconds. It's 60 calls by default, and 10 until your organization buys credits for the first time:

• Each POST /v1/analyses request counts as one call.
• Each POST /v1/batches request counts as one call, however many notes it has. The notes in a batch don't count.
• Notes analyzed one at a time in the web app count too, because the limit belongs to the organization.
• Retrying batch notes doesn't count.
• Deleting a result doesn't give its call back.

Reading, listing, searching, and deleting results, and reading credits, don't count toward this limit. Reads have their own limit: each API key can send 600 reads per minute. A read is any GET or HEAD request, or POST /v1/analyses/search. Every request the key makes counts toward the 600, but only reads are refused past it: a read gets 429 rate_limited with Retry-After until the next minute.

Over the limit, the response is 429 with Retry-After: 60:

{"error": {"code": "rate_limited", "message": "Too many analyses. Try again shortly."}}

If your organization needs a higher limit, write to support@medchartscan.io.

Uncharged notes

A note that ends out of scope or fails is never charged, but it still takes a full analysis. So each organization can have at most 25 such notes in any 24 hours, counted across the API and the web app, single notes and batch notes. Notes that fail because the analysis service itself is unavailable don't count.

Past the limit, every request that would analyze a note, including batches and retries, gets 429 too_many_uncharged_runs, with Retry-After giving the seconds until the oldest of those notes is more than 24 hours old. Notes already queued still run.

{"error": {"code": "too_many_uncharged_runs", "message": "25 notes from your organization ended out of scope or failed in the last 24 hours. ..."}}

If you reach it, check what your notes are: only office and outpatient E/M visits are in scope.

Batches are checked before their notes run, so a batch also counts the organization's notes in progress (queued or running) as if each could end out of scope. A batch, or a batch retry, is accepted only while the notes that ended out of scope or failed in the last 24 hours, plus the notes in progress, plus the batch's own notes add up to at most:

• 125 for an organization that has bought credits (25 plus 100, so a full 100-note batch always fits while you're under 25);
• 75 for an organization that hasn't bought credits yet (25 plus its 50 free credits, so a free trial can send all its free credits as one batch).

Otherwise the response is 429 too_many_uncharged_runs with Retry-After: 60. Send a smaller batch, or wait for the notes in progress to finish. Notes that end with a charge don't count, so a paying organization whose notes succeed can always send the next batch once the previous one finishes.

Unfinished batches

An organization can have 5 batches that haven't finished, counting batches started in the web app. A sixth gets 429 too_many_batches, with no Retry-After header. Poll your batches, and create the next one when one finishes.

{"error": {"code": "too_many_batches", "message": "An organization can have 5 batches in progress. Wait for one to finish."}}

Token requests

Each API key can get 20 access tokens per minute, and can send 20 wrong secrets per minute. Each IP address can have 30 failed authentications per minute; past that, each further failed request gets 429, but the right client ID and secret still get a token. These limits count in fixed one-minute windows that start on the minute, so a burst across the start of a minute can reach 40. Retry-After gives the seconds until the next minute. Reuse each token for its full hour to stay well under the limit. For more information, see Authentication.

Handle 429 responses

• Wait at least the number of seconds in Retry-After, then retry the same request with the same Idempotency-Key.
• Spread steady traffic over the minute instead of sending it in bursts.
• To analyze many notes, send them as batches: up to 100 notes count as one call.