Docs / Reference / PDF API limits, errors and retries

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 has status: "succeeded", pdf_url and the manifest (the render report).
  • 202: still rendering (status: "running"). Ask GET /v1/renders/{id} until status is succeeded or failed. A failed render has an error object with a code and message, 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 size6,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
HTML5 MiB
Files (assets), total25 MiB decoded, but the 6 MB request limit applies first
Pages per PDF20
Render time30 seconds
Render available through the API24 hours after completion; download the PDF before then
pdf_url valid for1 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.

HTTPCodeWhat to do
400INVALID_REQUESTCheck the JSON, the Content-Type header and the file names in assets
400INVALID_OPTIONSFix the option named in the message
401UNAUTHORIZEDCheck your API key and the Authorization: Bearer ... header
402QUOTA_EXCEEDEDThis mode's monthly limit is reached, including renders still running
404NOT_FOUNDUnknown render ID, or the render has expired
409IDEMPOTENCY_CONFLICTThat Idempotency-Key was already used for different content; pick a new one
413REQUEST_TOO_LARGE, HTML_TOO_LARGE, ASSETS_TOO_LARGEMake the request smaller (see Limits)
422TOO_MANY_PAGESThe document is longer than 20 pages
429RATE_LIMITEDReserved for future rate limiting; not returned by the public preview API. If introduced, honor Retry-After and retry with the same idempotency key
500INTERNAL_ERRORSomething 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
503EGRESS_UNAVAILABLEA temporary service problem; try the failed render again with a new Idempotency-Key
504TIMEOUTThe 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:

Terminal
  -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:

Terminal
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_url works 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.
  • 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.