Responses and Errors

Success responses

Endpoint	`response_type=json`	`response_type=binary`
`/v1/screenshots`	`screenshot_url`, `credits_charged`	The image file
`/v1/videos/rolling`	`video_url`, `credits_charged`	A redirect to the stored media URL

Screenshot binary responses also carry X-Page-Status-Code when ScreenshotLens can read the target page status.

Status codes

Status	Meaning	What to do
`200`	The capture completed.	Read the file or the JSON body.
`400`	Validation failed.	Fix the query string.
`401`	Missing or invalid authentication.	Check `api_key`.
`402`	Not enough credits.	Add credits or send a cheaper request.
`500`	The render or the platform failed.	Retry, then check Usage Logs.

Validation errors

A 400 response names the problem in an error field.

{
  "error": "url must be a valid http or https URL"
}

Most validation failures come from a missing url, a response_type other than binary or json, an unrecognized enum value, or a viewport or timing value outside the limits listed on the Screenshot API and Rolling Video API pages.

Credit errors

When the wallet balance cannot cover the request, nothing is rendered and the API returns 402 Payment Required with the shortfall.

{
  "error": "insufficient_credits",
  "balance": 3,
  "required": 5,
  "breakdown": [
    {
      "feature": "base",
      "cost": 5,
      "description": "video_rolling"
    }
  ]
}

A 402 is an account state, not a transient failure, so retrying the same request will not clear it.

Target page errors

ScreenshotLens records the target page status separately from the API response status. A page that answers 404 still produces a 200 capture of whatever it rendered, and that capture is free.

Usage Logs shows both statuses side by side.

Idempotency

Capture endpoints accept an optional Idempotency-Key header. Without it, every request gets its own generated key, so a client that retries after a network interruption is charged twice for what it sees as one capture. Send your own key when a retry should settle as a single charge.