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.
429	Too Many Requests	Monthly render limit reached. Upgrade your plan or wait until the next billing cycle.
500	Internal Server Error	Render or browser failure. The `error` field contains details.
503	Service Unavailable	All browser slots are busy or `render_when_ready` timed out (30s). Retry with exponential backoff.

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.
`Monthly render limit reached`	You have used all renders for this billing period. Returns `429`. Upgrade or wait for renewal.
`Maximum 25 requests per batch`	Reduce the `requests` array in `/v1/render/batch` to 25 items or fewer.
`This plan does not include full renders`	The `/v1/render/full` endpoint requires the $49/month plan or higher.

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)