The public API applies two main rate limits. A pre-auth IP limit defends against brute-force key enumeration, and a per-key limit is sharded by route class. Both return rate_limit_exceeded (HTTP 429) when exceeded. Invite emails to one email address have a further limit. See Per-recipient invite limit.
How rate limits work
Section titled “How rate limits work”The IP limit runs before authentication — coarse enough to shed abuse without affecting legitimate traffic.
The per-key limit runs after authentication and is sharded by route class so your read traffic does not crowd out your session-create traffic. Every route belongs to exactly one class, and a request counts against that class alone. The classes are:
sessions:create:POST /v1/sessions.sessions:read_report:GET /v1/sessions/{id}/report.pdf. Capped well below ordinary reads, because every call renders a document.sessions:read_image:GET /v1/sessions/{id}/idv-image/{artifact}. Flat at 120 requests per minute on every tier,customincluded. See Evidence images.idv:create:POST /v1/id-verification, the standalone ID-scan endpoint.watchlist:search:POST /v1/watchlist/search, the standalone watchlist screening endpoint.applicants:create:POST /v1/applicants, and the applicant update and delete routes.dsar:create:POST /v1/data_subject_requests. Capped low, on a 24-hour window rather than a 60-second one.reads: the list and retrieve reads, for exampleGET /v1/sessions,GET /v1/sessions/{id},GET /v1/applicants,GET /v1/workflow-templatesandGET /v1/wallet.global: the class for every route that has no more specific class of its own. That includes the verification actions (cancel, resend, reset, get a new link, manual review, notes, skip a step, mint a token) and the workflow-template and link writes.
Each organization has a tier (standard, elevated, enterprise, or custom). New organizations start on standard. Most classes scale with the tier, but three do not move the way you would expect. sessions:read_report is flat from elevated upward, so only the standard to elevated step raises it. sessions:read_image and dsar:create are flat on every tier including custom, so no tier change raises them at all.
Route classes are an internal throttling dimension, independent from the scopes you grant a key: route_class names the traffic bucket a route falls into, not a scope you hold. A key granted only sessions:write still shows route_class: "sessions:create" in a 429 from POST /v1/sessions, since the class name predates a later scope simplification and was kept as-is so existing rate-limit tooling and alerts do not need to change.
Two class names read like scope names and are not. sessions:read_image is a class only: there is no scope by that name, and the scope that authorizes the evidence-image route is sessions:read_report. sessions:read_report is both a class and a scope, and they are still separate things: holding the scope says you may call the route, while the class says which budget the call spends. Grant scopes from the scope reference; never infer one from a route_class you saw in a 429.
Rate-limit headers
Section titled “Rate-limit headers”Every authenticated response carries the per-key limit state:
X-RateLimit-Limit: 1000X-RateLimit-Remaining: 873X-RateLimit-Reset: 1717000060X-RateLimit-Window: 60X-RateLimit-Limit: the request budget for the current window.X-RateLimit-Remaining: how many requests are left before429.X-RateLimit-Reset: UNIX epoch seconds when the oldest counted request ages out of the window.X-RateLimit-Window: window length in seconds.
Track X-RateLimit-Remaining and slow down before you reach zero — it is cheaper than handling 429s reactively.
When you hit the limit
Section titled “When you hit the limit”A 429 rate_limit_exceeded response includes details inside the error envelope:
{ "error": { "code": "rate_limit_exceeded", "message": "Rate limit exceeded for this API key", "request_id": "req_...", "details": { "reset_at": 1717000060, "limit": 100, "window_seconds": 60, "route_class": "sessions:create", "tier": "standard" } }}Back off until reset_at, then retry. Use exponential backoff with jitter if you are processing a queue — synchronizing every worker on reset_at just hits the next window’s limit.
After a per-key limit’s 429, if you send an Idempotency-Key to a route that honors it, use a new key for the retry. Checktiv stores the refusal under the old key and replays it when you repeat the request with that key. The header is not honored by the session browser_token, workspace_token and regenerate_link endpoints. The IP limit’s refusal is not stored.
Per-recipient invite limit
Section titled “Per-recipient invite limit”Invite emails have their own limit. It protects one email address from many invites, and it is the same on every tier.
Three API requests share one count of the invite emails that your organization sends to one email address. The limit is at most three invite emails in an hour. The requests are:
POST /v1/sessionswithsend_invite: true.POST /v1/sessions/{id}/resend.POST /v1/sessions/{id}/reset_and_resend.
Other invites do not use this count. Send invite in the console and the CSV import each have their own limits.
Each email address has its own count in each organization. An address in another organization does not change your count. For these API requests, test mode and live mode share one count.
When you hit the invite limit
Section titled “When you hit the invite limit”resendandreset_and_resendrefuse the next request with429 rate_limit_exceeded.- A refused
reset_and_resendchanges nothing. It sends no email, it does not rotate the link, and it does not reset progress. Rotating the link replaces the single-use link and theclient_token. For a verification from a reservation in a connected system, it does not stop the reservation’s own link. To stop that link, cancel the verification. - To rotate the link before
reset_at, choose Generate new link on the applicant’s detail page in the console. The page offers it when it says the link was already used or has expired. That action sends no email and does not use the invite limit. - While the page shows the link to copy, the console offers no rotation, so retry
reset_and_resendafterreset_at. To replace that link sooner, callPOST /v1/sessions/{id}/regenerate_link. It issues a new single-use link without an email and keeps theclient_token. It does not use the invite limit. POST /v1/sessionswithsend_invite: truestill creates the verification. It sends no invite, and the response does not say so. Deliverapplicant_urlfrom the response, send the invite from the applicant’s detail page in the console, or callresendafter an hour.- Checktiv refuses a request for a finished, paused, or expired verification with its own
409. That request does not use the limit, unless the verification changes while the request runs.
The details of this 429 have three values:
reset_at: the time, in UNIX epoch seconds, when the oldest counted invite email leaves the window. You can then send one more invite email.limit: the number of invite emails that the window allows.window_seconds: the length of the window in seconds.
This 429 has no route_class or tier in its details, because the limit does not depend on them. Its window_seconds is 3600. The IP limit also answers 429 with no route_class or tier, but with a shorter window_seconds. Read window_seconds to tell the two apart.
The X-RateLimit-* headers on this response show the per-key limit of the route class. They do not show the invite limit, and X-RateLimit-Remaining can show a large number on the response that refuses you.
Retry after reset_at. If you send an Idempotency-Key, use a new key for the retry. Checktiv stores the refusal under the old key and replays it when you repeat the request with that key.
Burst vs sustained rate
Section titled “Burst vs sustained rate”The per-key limits and the invite limit are sliding-window counts. A request counts for one window length after you make it, so reset_at is when the oldest counted request ages out. The IP limit counts requests in fixed 60-second windows. These limits are counts, not token buckets. A burst up to the limit passes, and long-term sustained throughput is bounded by the limit. The IP limit and most per-key limits use a 60-second window; dsar:create uses 24 hours. The invite limit uses one hour.
Asking for a higher limit
Section titled “Asking for a higher limit”If you consistently see rate_limit_exceeded and adding backoff is not enough, contact support. See the API error codes.
The flat classes and the invite limit need a different fix, because a tier change will not move them:
- For
sessions:read_report, fetch a verification’s report once and keep it in your own storage under your own retention policy, rather than re-fetching it per page view. - For
sessions:read_image, readidv.available_imagesonGET /v1/sessions/{id}first and request only the images it lists. That removes the wasted request per missing image, which is the usual cause of hitting this class. See Evidence images. - For the per-recipient invite limit, retry a refused
resendorreset_and_resendafterreset_at. To deliver a link sooner, get a new single-use link fromPOST /v1/sessions/{id}/regenerate_linkand send it over your own channel. That call does not use the invite limit.POST /v1/sessionswithsend_invite: trueover the limit still creates the verification. It sends no invite, and the response does not say so. Its next steps are in When you hit the invite limit.
If a legitimate workload still needs more headroom on either class, contact support with the request_id from one 429 and describe the traffic shape; both caps exist to protect the rendering and evidence paths, so raising one is a review rather than a self-serve change.