Errors and limits

Error format

An error returns a 4xx or 5xx HTTP status code and a JSON body with a single field, error, that describes the problem. This message is meant for your logs, not for your users: base your logic on the status code.

402 response

HTTP/1.1 402 Payment Required
Content-Type: application/json

{ "error": "document limit reached for the Free plan (100)" }

Errors detected before the request reaches the API itself (body too large, Content-Type not accepted) may carry extra fields, such as statusCode and message. The error field is always present.

Status codes

Code	Name	Meaning
400	Bad Request	Invalid request: empty body, malformed header, or invalid fileId, email or validity period.
401	Unauthorized	API key missing, unknown or revoked.
402	Payment Required	Plan limit reached (number of documents, storage). Upgrade to a higher plan or free up space.
403	Forbidden	Action not allowed on this resource, for example downloading a `source` document.
404	Not Found	Resource doesn't exist, link expired or revoked, or resource belongs to another account.
413	Payload Too Large	File larger than 25 MB.
415	Unsupported Media Type	Content is not a PDF, JPEG or PNG.
422	Unprocessable Entity	File recognized but unreadable, for example a corrupted PDF.
429	Too Many Requests	Reserved. Not currently returned by the API, but handle it in your code.
5xx	Server error	An incident on our side. Retry with increasing backoff; read requests can be safely replayed.

Successful responses use 200, 201 for a creation (POST /files, POST /views) and 204 with no body for a deletion.

Limits per plan

Limit	Free	Pro	Business
Documents	100	5,000	Unlimited
Storage	1 GB	25 GB	200 GB
Maximum link duration	7 days	30 days	30 days
API keys	2	10	50
Custom-branded watermark	No	Yes	Yes
Access log export	No	No	Yes

Storage counts the size of uploaded files. Exceeding a limit returns 402 without saving anything. GET /v1/account returns your plan's limits and your current usage at any time.

Accepted files

Maximum size: 25 MB per file. Larger files get 413.
Types: PDF, JPEG and PNG. Other formats (Word, HEIC, TIFF, etc.) must be converted before upload.
The type is detected from the file's first bytes, not from the declared Content-Type header. A file renamed to .pdf that isn't one gets 415, and the response's contentType field always gives the actual type.
File names are limited to 200 characters.

Throughput and page rendering

Page rendering is queued: a limited number of pages are rendered in parallel on the server, and the rest wait their turn. Expect about one second per page. In practice:

Don't request every page of a long document at once; load them as the reader progresses.
Set a timeout of at least 30 seconds on your server-side calls.
Don't cache pages to serve them again: each image carries the timestamp of its display and must be requested again.

Next pageSecurity model