Errors - spoolpdf

Non-PDF responses use this envelope:

{
  "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

⌘I