Errors

Every status code the render API returns, what causes it, and what to do next.

A failed request returns JSON with a single error string:

{ "error": "Provide either html or url" }

A successful one returns bytes, so branch on response.ok — never on the body’s shape.

Status codes

Status	Meaning	What to do
`400`	The body failed validation — a missing source, an unknown field, a value out of range.	Fix the request. Retrying won’t help.
`401`	The API key is missing, malformed, disabled, or deleted.	Check the `authorization` header and the key’s status in the dashboard.
`402`	The monthly render limit is used up.	Upgrade the plan, or wait for the next month. See Plans and limits.
`404`	`templateId` doesn’t exist, or belongs to another account.	Copy the ID again from the dashboard’s Templates tab.
`5xx`	The render itself failed — the page didn’t settle, the browser errored, or the renderer was unavailable.	Retry with backoff. If it repeats for the same document, the cause is usually in the page.

Common causes

Provide either html or url — /v1/render needs one of them. On /v1/render/template, neither is accepted; send templateId instead.

Unrecognized key on a field you expected to work — the body is validated strictly, so a typo (pageFormat for pdfFormat) fails rather than being ignored. Check the field against Render options.

HTML payload is too large — the document exceeded 5 MB, almost always because of inlined data: images. Host them and reference absolute URLs instead.

Template not found — the ID is wrong, the template was deleted, or the key belongs to a different account than the template.

When the file renders but looks wrong

An empty, half-drawn, or unstyled document is a page problem, not an API error — the render succeeded, it just captured the page too early or without its assets.

Missing styles, fonts, or images — relative URLs in html have no origin to resolve against. Use absolute URLs, or inline the CSS in a <style> block.
Blank or partial content — the page draws after load. Raise waitUntil to networkidle and add waitForTimeout in the 300–1000 ms range.
Only the top of a long page — set fullPage: true for images; for PDFs, the page grows automatically, so check for a container with a fixed height or overflow: hidden.
PDF missing backgrounds — printBackground defaults to true, so a missing background usually comes from @media print rules on the page; render with media: "screen" to confirm.
Blurry images — raise deviceScaleFactor (up to 4), or quality for jpg and webp.

The dashboard sandbox is the quickest way to iterate: same renderer, same options, no deploy between attempts.

Retrying

4xx responses are deterministic — the same request fails the same way, so fix it rather than retry it. 5xx responses are worth retrying with exponential backoff.

Keep in mind that a render that fails after it starts has already counted against your monthly quota, so cap retries at two or three rather than looping.