Errors

Errors are returned as JSON with an error object containing a code and a human-readable description. There are two shapes depending on the error:

• Validation errors (VALIDATION_ERROR) use a messages array — one entry per failed field:

{ "error": { "code": "VALIDATION_ERROR", "messages": ["html is required", "options.scale must be between 0.1 and 2.0"] } }

• All other errors use a single message string:

{ "error": { "code": "INVALID_REQUEST", "message": "invalid request body: json: unknown field \"bogus\"" } }

When parsing errors, read error.code first, then check for error.messages (array) or error.message (string).

HTTP	Code	Meaning	What to do
400	READ_ERROR	The request body couldn't be read.	Retry; check your client isn't truncating the body.
400	INVALID_REQUEST	The body wasn't valid JSON, couldn't be parsed, or contained an unknown field.	Fix the JSON; send only documented fields.
422	VALIDATION_ERROR	One or more field values failed validation (see messages).	Correct the listed fields. Common causes: missing html, bad dimension, out-of-range scale, unsupported output/format.
422	SSRF_BLOCKED	A URL referenced in your HTML was blocked by the security screen.	Remove or replace the disallowed URL (see Remote assets & security).
401	(unauthorized)	Missing, malformed, or revoked API key.	Check your Authorization header and key status.
429	QUOTA_EXCEEDED	You've hit your plan's monthly render limit.	Wait for the next billing period or upgrade your plan. The message includes your limit and plan.
429	RATE_LIMITED	You're sending requests too quickly.	Back off and retry. See the X-RateLimit-Reason header and Limits & quotas.
502	RENDER_FAILED	The render engine failed to produce a PDF.	Retry; if it persists, simplify the HTML and contact support with the X-Render-ID.
200	ALREADY_RENDERED	An idempotent replay (see Idempotency).	This is not a PDF — see the idempotency notes.

Always check the HTTP status code. A 200 with Content-Type: application/pdf is a successful render; any other response is JSON describing the problem.