Tools

Error Handling

Every failure surfaces as a JSON document with a single detail field — predictable, parseable, easy to log.

Error response format

On any rendering failure the API responds with HTTP 500 and a JSON body. The detail field contains a human-readable description of what went wrong inside the renderer.

{
  "detail": "Failed to render page: net::ERR_NAME_NOT_RESOLVED at https://nope.invalid"
}

Common causes

Invalid or unreachable URL

The target host returned a network error, refused connection, or resolved to a non-routable address.

Render timeout

The page exceeded the internal render timeout (typically 30s). Try optimize_speed: true or a simpler URL.

Browser crash

A heavy script or memory spike crashed the renderer. The warm-boot supervisor will recover automatically — just retry.

Blocked by target

The destination served a 4xx (e.g. 403 Forbidden) or a captcha. The API faithfully captures whatever the page renders.

Handling errors in your client

const res = await fetch(url, { method: "POST", body });

if (!res.ok) {
  // Server returned 500 with JSON detail
  const { detail } = await res.json();
  console.error("Screenshot failed:", detail);
  return null;
}

const blob = await res.blob();

Always retry once

Transient browser crashes self-heal thanks to the warm-boot supervisor. A single retry after a 500 response succeeds in the vast majority of cases.

Status codes you may see

200 — PNG bytes returned successfully.
422 — Invalid request body (missing url, wrong type).
500 — Internal render failure with JSON detail.