Limits and errors

What the API allows, what happens past it, and every error it can answer with.

What counts

One request that ends with a 2xx status is one PDF, whatever the route, the number of pages or files. Failed requests count nothing. More in How it works.

When the plan’s PDFs are used

Each PDF of a billing period comes from the first of these with room left:

The PDFs of your plan for this period.
Credits you bought in advance, at your plan’s price per extra PDF, taken at once. This holds for every plan, Free included.

With neither left, requests get 429 with code 42903 (“credits needed”) until the next period or until you buy credits. With “Stop at the plan limit” switched on, requests stop at the plan’s PDFs even when you have credits (42902). Contract accounts are invoiced for extra PDFs up to an agreed limit instead (42904). See Plans and billing.

Limits per plan

PDFs per month	Largest request	Requests per minute
100 (Free)	5 MB	10
500	20 MB	60
1,000	20 MB	60
2,500	20 MB	60
5,000	20 MB	60
10,000	50 MB	120
25,000	50 MB	120
50,000	100 MB	300
100,000	100 MB	300
200,000	100 MB	300
500,000	100 MB	300

The largest request is the whole request body. Requests per minute are counted per account, over all its keys.

Time

Limit	What happens
60 seconds for the conversion	The engine stops and answers `503` (plain text). Webhook jobs too.
65 seconds for the whole request	The gateway stops and answers `504`, code `50410`.

Errors

Two kinds of errors come back.

From the gateway (key, plan, size, rate, availability): JSON with a numeric code, a sentence for people and a link here.

{
  "code": 42903,
  "error": "Your credits are used up. Buy credits at https://pdfdispatch.com/app/credits.",
  "link": "https://pdfdispatch.com/docs/limits"
}

Status	Code	Why	What to do
401	`40101`	No key was sent, or the key is wrong or has been revoked.	Check the `Authorization` header (see Authentication). Make a new key if this one was revoked.
401	`40102`	The account cannot make PDFs right now. It is blocked or closed, or the subscription is unpaid (the card was declined and every retry has failed).	Pay the open invoice in the web app, or write to support.
404	`40410`	Nothing lives at this method and path. The API only answers `POST` requests to its routes, all under `/v1/`.	Check the method (it must be `POST`) and the path against the route list, including the `/v1` at the start.
413	`41301`	The request’s `Content-Length` is bigger than your plan’s largest request. It was refused before the upload started.	Send smaller files (compress images, split the job), or move to a plan with a bigger limit.
413	`41310`	The body grew past your plan’s largest request while it was being uploaded (usually a request without `Content-Length`). The upload was cut off.	The same as 41301.
429	`42902`	“Stop at the plan limit” is switched on for your account, and the plan’s PDFs for this period are used. Any plan, Free included.	Switch the setting off so extra PDFs are paid from credits, move to a bigger plan, or wait for the next period.
429	`42903`	Credits needed: your plan’s PDFs for this period are used, and your credit balance cannot pay for the next PDF. Any self-serve plan, Free included.	Buy credits in the web app, move to a bigger plan, or wait for the next period.
429	`42904`	Contract accounts only: the agreed monthly limit for extra PDFs is reached, or the contract has no extra PDFs.	Write to support to change the limit.
429	`42910`	More requests in this minute than your plan allows.	Wait the number of seconds in the `Retry-After` header, then send it again. Spread bursts out, or queue them on your side.
503	`50301`	Your key could not be checked just now (a short outage on our side).	Retry after a few seconds, with a growing pause between attempts.
503	`50310`	The PDF engine could not be reached or failed while answering.	Retry after a few seconds, with a growing pause between attempts.
504	`50410`	The request took longer than 65 seconds from start to end, upload and download included, and was stopped.	Make the job lighter (smaller images, fewer pages, less waiting), split it into several requests, or check that your upload is not slow.

Retired: 42901. Older integrations may have seen this code. It meant that a Free account had used its 100 PDFs of the month. The API no longer answers with it: a Free account now gets 42903 when it has no credits, or 42902 with “Stop at the plan limit” on.

From the conversion (the request itself): plain text that names the problem.

Status	Means	Do this
400	A field is missing or wrong, a file is of the wrong type or damaged, a wait expression failed, or a combination is not allowed. The message says which.	Fix the request. It fails the same way every time.
403	A URL (`url`, `downloadFrom`, webhook) points to an address the API may not reach.	Use a public address, or send the content as a file (details).
409	A check you asked for failed: the page answered with an error status, a resource failed, or the page threw an exception (the `failOn...` fields). The message lists what.	Fix the page, or loosen the check.
415	The body is not `multipart/form-data` (for example URL-encoded or JSON).	Send a multipart body, even when it has no files (details).
429	The engine’s queue is full for a moment (plain text, no `code`).	Retry after a few seconds.
500	The engine failed on a valid request, for example on an unusual Office document.	Retry once; if it fails again, write to us with the `X-Request-Id`.
503	The conversion took longer than 60 seconds, or the browser crashed on the page.	Make the job lighter or split it; retry for a crash.

None of these errors counts as a PDF.

Still stuck?

Write to [email protected] with the X-Request-Id of the request, the route, and what you expected. We can see how a request ended, never its content.