> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spoolpdf.nandra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> JSON error envelope and codes returned by the render API.

Non-PDF responses use this envelope:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "exactly one of html or url is required",
    "request_id": "00000000-0000-0000-0000-000000000000"
  }
}
```

`X-Request-Id` is also set as a response header.

## Codes

| Code                    | Status | Meaning                                                                                  |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------- |
| `unauthorized`          | 401    | Missing or invalid API key                                                               |
| `unauthorized_internal` | 401    | Internal MCP path misconfigured (not a public caller error)                              |
| `validation_error`      | 400    | Invalid JSON or field (duration, cookies, pages + single\_page, auth + Authorization, …) |
| `payload_too_large`     | 400    | Body over 5 MB                                                                           |
| `ssrf_blocked`          | 422    | Private/loopback `url`, `css`, or `javascript` URL                                       |
| `subscription_inactive` | 403    | Plan not active                                                                          |
| `rate_limited`          | 429    | Trial RPM exceeded                                                                       |
| `concurrency_limit`     | 429    | Too many in-flight renders for the plan                                                  |
| `render_failed`         | 502    | Gotenberg/Chromium failed (timeout, wait never true, HTTP fail-on-status, …)             |
| `not_found`             | 404    | Unknown account on the internal MCP path                                                 |

## Typical fixes

| Symptom                                                         | Fix                                                             |
| --------------------------------------------------------------- | --------------------------------------------------------------- |
| `wait_delay must be a duration`                                 | Use `2s` or `500ms`, not a bare number                          |
| `extra_http_headers cannot include Cookie`                      | Move the session to `cookies`                                   |
| `cookies[0] requires name, value, and domain`                   | Domain is required                                              |
| `pages cannot be combined with single_page or auto height`      | Drop `pages` or the auto format                                 |
| `auth cannot be combined with extra_http_headers Authorization` | Use one or the other                                            |
| `ssrf_blocked`                                                  | Public `http(s)` only                                           |
| `render_failed` after a wait                                    | Selector/expression never became true before the render timeout |