Docs / Reference

Errors

Every error uses the same envelope and a non-200 status. The code is stable — branch on it, not the message.

error envelope

{
  "error": {
    "code":    "quota_exceeded",
    "message": "Monthly capture quota reached. Resets 2026-07-01…"
  }
}

Error codes

HTTP	Code	Meaning · what to do
401	`unauthorized`	Missing, invalid or revoked key. Check the Bearer header.
422	`invalid_url`	Not an absolute http(s) URL, or the host is private/unreachable. Fix the URL.
422	`invalid_format`	`format` must be `png`, `jpeg` or `pdf`.
422	`invalid_request`	Conflicting parameters — e.g. url+html together, omit_background without png, clip_width without clip_height.
422	`region_unavailable`	Only `region=eu` exists today; `us` is on the roadmap.
422	`render_failed`	The page couldn't be rendered (dead host, refused connection, bad TLS…). Not billed. Retrying usually only helps if the target site recovers.
422	`sitemap_failed`	`/v1/sitemap` couldn't download or parse the sitemap (timeout, >5MB, not XML, no URLs found). Nothing billed.
429	`rate_limited`	Over your plan's req/s. Honor `Retry-After` (1s) and retry.
429	`quota_exceeded`	Monthly captures used up. Buy credits ($5/1,000, never expire) or upgrade; resets on the 1st (UTC).
502	`lighthouse_failed`	`/v1/lighthouse` couldn't analyze the page. The reserved quota unit is refunded. Retry in a minute.
503	`upstream_unavailable`	Capture engine briefly down or saturated. Honor `Retry-After` (30s) — these resolve in seconds. Not billed.

Billing on errors

Failed captures are never billed. Quota is reserved when a request starts and refunded automatically on any failure — including upstream timeouts. Cached repeats are also free.

Retry strategy

Safe defaults: retry 429 and 503 after their Retry-After; treat 422 as permanent for that input; never auto-retry 401.