Docs menu · PDF API limits, errors and retries
Reference
PDF API limits, errors and retries
What one call can do, what each error means, how to retry without creating a second PDF, and how renders are counted.
How a request works
POST /v1/pdf takes JSON (Content-Type: application/json) with html and, optionally, options and assets.
201: the PDF is ready. The answer hasstatus: "succeeded",pdf_urland themanifest(the render report).202: still rendering (status: "running"). AskGET /v1/renders/{id}untilstatusissucceededorfailed. A failed render has anerrorobject with acodeandmessage, and does not count.
Add ?response=binary to POST /v1/pdf to get the PDF file itself in the answer when it is ready right away (with the render ID in the X-Render-Id header and the warning count in X-Render-Warnings); otherwise you get the 202 answer above.
Limits
| Limit | |
|---|---|
| Request size | 6,000,000 bytes in total (6 MB), including HTML and JSON. Base64 adds about a third to file size, leaving less than 4.5 MB for files |
| HTML | 5 MiB |
Files (assets), total | 25 MiB decoded, but the 6 MB request limit applies first |
| Pages per PDF | 20 |
| Render time | 30 seconds |
| Render available through the API | 24 hours after completion; download the PDF before then |
pdf_url valid for | 1 hour; ask for the render again for a new link |
The 6,000,000-byte limit applies to the whole JSON request, including base64-encoded files. The larger decoded-files limit does not increase what fits in a request.
MB means 1,000,000 bytes; MiB means 1,048,576 bytes. The request limit applies to the whole JSON body.
Errors
Errors look like {"error": {"code": "...", "message": "..."}}. Use the code and message to decide what to do next.
| HTTP | Code | What to do |
|---|---|---|
| 400 | INVALID_REQUEST | Check the JSON, the Content-Type header and the file names in assets |
| 400 | INVALID_OPTIONS | Fix the option named in the message |
| 401 | UNAUTHORIZED | Check your API key and the Authorization: Bearer ... header |
| 402 | QUOTA_EXCEEDED | This mode's monthly limit is reached, including renders still running |
| 404 | NOT_FOUND | Unknown render ID, or the render has expired |
| 409 | IDEMPOTENCY_CONFLICT | That Idempotency-Key was already used for different content; pick a new one |
| 413 | REQUEST_TOO_LARGE, HTML_TOO_LARGE, ASSETS_TOO_LARGE | Make the request smaller (see Limits) |
| 422 | TOO_MANY_PAGES | The document is longer than 20 pages |
| 429 | RATE_LIMITED | Reserved for future rate limiting; not returned by the public preview API. If introduced, honor Retry-After and retry with the same idempotency key |
| 500 | INTERNAL_ERROR | Something went wrong on our side. For a create whose outcome is unknown, retry with the original Idempotency-Key. If error.render_id is present, check the render's status before resubmitting. Use a new key only to rerender a document after a confirmed failure |
| 503 | EGRESS_UNAVAILABLE | A temporary service problem; try the failed render again with a new Idempotency-Key |
| 504 | TIMEOUT | The page took longer than 30 seconds to render |
Retrying safely
Networks fail sometimes. To retry a request without creating a second PDF, give it a name of your own in the Idempotency-Key header, for example your invoice number. In the Quickstart request, add this line before the -d line:
-H "Idempotency-Key: invoice-1042" \
If Stolid PDF has already seen that name with the same content in the last 24 hours, it returns the original render instead of making a new one, and you are not counted twice. Use a new name for each new document. The header is optional, and the client libraries add one to every call for you.
Your API key authenticates you; the Idempotency-Key identifies one document request.
Usage in the preview
The preview is free. Each account includes:
- 500 renders a month with your
stolid_live_key. - 100 test renders a month with your
stolid_test_key: handy for automated tests.
A render counts when its status is succeeded, even if its report contains warnings. A failed render is not counted. If a response is interrupted after a render succeeded, fetch that render by its ID or repeat the request with the same Idempotency-Key; either way it is counted once. There is no per-second rate limit during the preview. To see where you are this month:
curl -sS "https://api.stolid.dev/v1/usage" -H "Authorization: Bearer $STOLID_API_KEY"
The response includes mode, renders, limit, period_start and period_end. For example, after one successful live render in a new month, renders is 1 and limit is 500. The "usage": {"renders": 1} inside a single render's answer counts only that render.
When the month's renders are used up, new requests get 402 QUOTA_EXCEEDED until the first day of the next month (UTC). There is no charge during the preview.
Keeping your key safe
- Treat your API key like a password. Keep it in an environment variable or a secret store, and call Stolid PDF from your server, not from a web page or mobile app.
- The
pdf_urlworks for anyone who has it until it expires, so do not post it publicly. - Lost or leaked a key? Write to hello@stolid.dev with the key's first 16 characters (for example
stolid_live_AbCd), never the whole key, to request a replacement.
Related
- API reference: HTTP endpoints, status codes, and common request and response fields. See the OpenAPI file for complete schemas.
- Clients: the typed errors that the Python and Node clients raise.
Public preview: free while we work with early users. Use sample data; there is no uptime commitment yet.