Errors

HTTP status codes and error response format.

Error Response Format

All errors return a JSON body with an error field describing what went wrong.

JSON

{
  "error": "url must start with http:// or https://"
}

Status	Meaning	Common cause
200	Success	The render completed successfully.
201	Created	A template was saved (`POST /v1/template`).
400	Bad Request	A required parameter is missing or invalid.
401	Unauthorized	`x-api-key` header missing or incorrect.
404	Not Found	The `template_id` does not exist.
500	Internal Server Error	Render or browser failure. The `error` field contains details.

Error message	Fix
`Unauthorized`	Add `x-api-key: YOUR_API_KEY` to the request headers.
`html or template_id is required`	Pass either `html` or `template_id` in the request body.
`url is required`	Include a `url` field in the body for `/v1/screenshot`.
`url must start with http:// or https://`	Make sure the URL includes the full scheme.
`Template '{id}' not found`	The `template_id` was not found. Check the ID or create the template first.
`Page.goto: Timeout 30000ms exceeded`	The target URL took too long to respond. Check if the site is reachable.
`Selector '...' error`	The CSS selector didn't match any element. The API falls back to a full-viewport capture.

URL screenshot: 30 second hard timeout for page.goto()
ms_delay: capped at 30,000 ms on all endpoints
Font download: 10 second timeout per Google Fonts request; fails gracefully (uses CDN instead)