Rate limit & quotas

You can use a certain number of requests per month, defined by your plan.

You can use every request of that quota; once it is used up, the API returns a 429 HTTP status code (error code quota_exceeded, with quota.resets_at in the body; the first such answer also has a Retry-After header until the quota resets), and you either need to upgrade your plan or wait until your quota resets. Your plan also sets how many renders you can run at the same time (concurrency). The free plan also has a rate limit of 10 requests per minute. If you exceed it, the API returns a 429 HTTP status code (rate_limit_exceeded), and you have to wait until the end of the minute to make more requests; Retry-After says how many seconds that is. Paid plans have no per-minute limit. Not every request counts towards your monthly request volume.

On a paid plan you can avoid the 429 with optional overage: turn it on with a monthly spending cap on the Billing page of the dashboard. Requests past the quota are then billed at your plan's overage price (pricing) until the cap is reached. Overage is off until you turn it on, and the free plan has none.

Cost per request

A screenshot, a PDF, a markdown conversion and a render of HTML input each count as one request. The X-Cost header of a successful response tells you how many requests the call counted. A PDF, markdown or a render of HTML input counts the same with and without upload=1, and your quota is checked before it is rendered: if the quota does not cover it, the API answers 429 with quota.required instead of rendering it. A screenshot counts as one request with and without upload=1 (X-Cost: 1 on its JSON response), also against the free plan's per-minute limit; an async job of it is charged one request and refunded when it fails. A PDF, markdown or a render of HTML input requested with a sandbox API key costs nothing (X-Cost: 0).

Concurrency

Every plan is limited by the number of renders it runs at the same time; on paid plans this takes the place of a per-minute limit:

PlanRenders at the same time
Free2
Basic5
Premium10
Enterprise25

A request that would start one more render answers 429 with the error code concurrency_limit_exceeded and Retry-After: 1, before anything is rendered, and is not billed: send it again when one of your renders is done. Every render answers with X-Concurrency-Limit (your plan's number) and X-Concurrency-Remaining (how many more you could start right now). When our renderers are busy, a request can also answer 503 with the error code renderer_busy and Retry-After: 5, not billed. One account runs at most 8 renders on one of our render servers at a time, so that a single account never takes a whole server; above 8 renders at once (Premium and Enterprise), some requests can answer 503 renderer_busy while your plan's number is not reached. Send them again after Retry-After; they may go to another server.

Async jobs wait in a queue instead: your account may have its concurrency times 10 jobs queued or rendering at once.

Response headers

We attach specific headers to tell you your current quota and how much you have remaining in the period. The monthly headers are sent on every plan; the per-minute headers are only sent on the free plan.

X-RateLimit-Limit-Quota-Minute: 5
X-RateLimit-Limit-Quota-Month: 300

X-RateLimit-Remaining-Quota-Minute: 3
X-RateLimit-Remaining-Quota-Month: 199

The minute headers count on the gateway node that answered the request: X-RateLimit-Limit-Quota-Minute shows that node's limit (5), and with our two gateway nodes that makes the 10 requests per minute of the free plan. X-RateLimit-Remaining-Quota-Minute is what is left on that node.