Limits and errors
What counts as one PDF
- One successful request (an answer with status 2xx) is one PDF, whatever its number of pages, files or the route. A screenshot, a merge or a metadata read counts the same.
- A request that fails counts nothing: a wrong form field (400), a page that may not be fetched (403), a request that is too big (413), a refused request (429), a timeout or a server error (5xx).
- A webhook request counts when it is accepted (204).
- The month is your billing period; on the Free plan it is the calendar month (UTC).
When your plan's PDFs are used
Each PDF in a billing period is taken from the first of these that has room:
- Your plan's PDFs for the period.
- Your credits: each extra PDF takes your plan's price per extra PDF from your balance at once (on the Free plan €0.048).
When neither has room, requests get 429 (42903, credits needed) until the next period
or until you buy credits. This is the same on every plan, the Free plan
included. Nothing goes on an invoice. With "Stop at the plan limit" switched on, requests stop at your plan's
PDFs (42902) and no credits are used. Contract accounts follow their contract. Prices are on the
pricing page.
Limits per plan
| PDFs per month | Largest request (all files) | 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 |
A conversion may take up to 60 seconds; after that the answer is 503. For longer jobs, split the document or use a webhook.
Errors
Errors of the API's gateway (keys, limits, availability) are JSON, with a code to look up below:
{
"code": 42903,
"error": "Your plan's PDFs for this period are used. Buy credits to keep converting: https://pdfdispatch.com/app/credits.",
"link": "https://docs.pdfdispatch.com/limits/#42903"
}| Status | Code | What it means | What to do |
|---|---|---|---|
| 401 | 40101 | The key is missing, wrong or revoked. | Send a valid key (keys). |
| 401 | 40102 | Your account is blocked or closed. | Write to support. |
| 404 | 40410 | No such route. Every route is a POST under /v1/convert/, /v1/screenshot/ or /v1/pdf/ (or the older /v1/forms/). | Check the method and the path (endpoints). |
| 413 | 41301 | The request (its Content-Length) is bigger than your plan allows. | Send smaller files, or move to a bigger plan. |
| 413 | 41310 | The upload grew bigger than your plan allows while it was sent (a request without Content-Length). It was stopped. | As above. |
| 429 | 42902 | "Stop at the plan limit" is on, and your plan's PDFs for this period are used. | Switch it off, 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 credits do not pay the next PDF. Also on the Free plan. | Buy credits, move to a bigger plan, or wait for the next period. |
| 429 | 42904 | Contract accounts: the monthly overage limit agreed with us is reached, or the contract has no overage. | Write to support. |
| 429 | 42910 | Too many requests per minute for your plan. | Slow down, and retry after a few seconds. |
| 503 | 50301 | We could not check your key just now. | Retry after a few seconds. |
| 503 | 50310 | The PDF service is not available just now. | Retry after a few seconds. |
| 504 | 50410 | The PDF took longer than 65 seconds to make, and was stopped. | Make the page lighter (fewer or smaller images), or split it into several PDFs. |
None of these counts as a PDF. The code 42901 (the Free plan's limit) is no longer used: the Free plan pays its extra PDFs with credits too, so it gets 42903 or 42902.
Errors of the conversion itself
These come as plain text, with a message that names the problem, and count nothing either:
400 for a missing or wrong form field or a file type the route does not take, 403
for a URL the API may not fetch, and 503 when a conversion takes longer than 60 seconds.
Office conversions can also answer 500 when LibreOffice fails on a valid request; that one is
worth a retry. A 400 fails the same way every time: fix the request first.
Still stuck? Write to support@pdfdispatch.com with the X-Request-Id of the request.