Errors

An error response has a JSON body:

{
  "code": "unsupported_document",
  "error": "document not supported by the forme engine",
  "unsupported": ["unsupported property: box-shadow"]
}

Field	Content
`code`	Stable name of the cause.
`error`	Human-readable message.
`unsupported`	With `unsupported_document` only: one entry per feature outside the Forme subset.

Branch on code, not error. error is human-readable and may change; code is stable.

A 402 body also carries upgrade_url and resets_at; see Billing and credits.

Error codes

`code`	Status	Meaning	Retry or fix
`invalid_request_body`	400	The body is not JSON, a required field is missing or of the wrong type, or an option has an invalid value; `error` names the cause.	Fix the request.
`unknown_option`	400	`options` has a property that is not a page option.	Remove it; see Page setup.
`option_not_supported_by_engine`	400	The option is not available with the chosen engine (`scale` with Forme).	Remove the option or use Chromium.
`template_render_failed`	400	`/v1/render`: the template did not interpolate with `data`.	Fix the template syntax.
`unknown_asset`	400	`/v1/render`: the template references an `asset:<filename>` it has no asset for.	Upload the asset or fix the reference.
`invalid_api_key`	401	The key is missing or not recognized.	Create a key in the dashboard, or check the `Authorization` header.
`api_key_disabled`	401	The key is disabled.	Enable the key again, or use another key.
`api_key_expired`	401	The key is past its expiry date.	Move the key's expiry forward or clear it, or use another key.
`monthly_limit_reached`	402	The monthly allowance is spent and no credits were bought.	Upgrade, or wait for `resets_at`.
`credits_required`	402	The monthly allowance and the prepaid credits are spent.	Buy credits, or wait for `resets_at`.
`wrong_region`	403	The key belongs to a project in another region; the body names the `host` to call.	Send the request to `host`; see Regions.
`template_not_found`	404	`/v1/render`: no template with this id belongs to the key's project.	Check `template_id`.
`not_found`	404	No operation matches the method and path, or the host is not one of the API hosts.	Check the method, the path and the host.
`request_body_too_large`	413	The body, the interpolated template or the inlined assets exceed the plan's cap.	Reduce the document or data.
`output_pdf_too_large`	413	The PDF exceeds 25 MiB, the limit on every plan.	Reduce the document.
`unsupported_document`	422	The document uses features outside the Forme subset, listed in `unsupported`.	Change the document or use Chromium.
`engine_limit_exceeded`	422	The document is too large or too deeply nested for Forme.	Use Chromium.
`render_deadline_exceeded`	422	The render did not finish within the deadline: 30 seconds with Chromium, the CPU budget with Forme.	Reduce the document's size or complexity; with Forme, use Chromium.
`rate_limit_exceeded`	429	The project's per-second rate limit is exhausted.	Retry after `Retry-After` seconds.
`concurrency_limit_exceeded`	429	The plan's concurrent conversions are already in flight.	Retry after `Retry-After` seconds.
`failed_render_limit_reached`	429	The project's daily allowance of failed renders is spent; see Plans and limits.	Fix the document; retry after `Retry-After` (00:00 UTC).
`conversion_failed`	500	The renderer failed to produce a PDF.	Retry.
`internal_error`	500	An unexpected failure outside the conversion itself.	Retry.
`key_lookup_unavailable`	503	The key, or the template, could not be verified right now.	Retry after `Retry-After` seconds.
`renderer_unavailable`	503	The Chromium renderer could not start a browser.	Retry after `Retry-After` seconds.

A 422 is not billed, and the same document fails again. A 500 or 503 is not billed and is safe to retry.

Response headers

Header	On	Content
`X-Request-ID`	Every response	The id generated for this call. Quote it when reporting a problem: it is the id of the call in your call log.
`X-Render-Time-Ms`	200	Milliseconds the conversion took.
`Server-Timing`	200, 402, 422, 429	Stage durations of this request in milliseconds: lookup, reserve, prepare, render, total.
`X-Asset-Fetch-Ms`	200, `/v1/render`	Milliseconds taken to have every referenced asset in hand. Present when the template references assets.
`X-RateLimit-Limit`	200, 429	Requests allowed per second. Absent when the plan has no rate limit.
`X-RateLimit-Remaining`	200, 429	Requests left before the rate limit applies. Absent when the plan has no rate limit.
`Retry-After`	429, 503	Seconds until a retry can succeed.
`X-Skipped-Resources`	200, 422	Number of remote resources left out. Absent when none was.
`X-Skipped-Resources-Detail`	200, 422	Up to ten skipped resources as `<reason>=<url>` pairs; see Remote resources.

Errors

Error codesCopy Anchor Link

Response headersCopy Anchor Link

On this page

Error codes

Response headers