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

```bash
  -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:

```bash
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](mailto: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](https://stolid.dev/docs/api/): HTTP endpoints, status codes, and common request and response fields. See the [OpenAPI file](https://stolid.dev/openapi.json) for complete schemas.
- [Clients](https://stolid.dev/docs/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.

[Preview Terms](https://stolid.dev/legal/terms/) · [Acceptable use](https://stolid.dev/legal/terms/#acceptable-use) · [Privacy Policy](https://stolid.dev/legal/privacy/) · [Data handling](https://stolid.dev/data/) · Report abuse or copyright infringement: hello@stolid.dev

© 2026 Stolid · Operated by an individual in Washington, USA

Source: https://stolid.dev/docs/limits/
