# Responses and Errors

Source: https://docs.screenshotlens.com/docs/api/responses-errors
Summary: Status codes, error bodies, and what to do about each one.

## 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](https://docs.screenshotlens.com/docs/dashboard/usage-logs). |

## Validation errors

A `400` response names the problem in an `error` field.

```json
{
  "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](https://docs.screenshotlens.com/docs/api/screenshots) and [Rolling Video API](https://docs.screenshotlens.com/docs/api/rolling-video) pages.

## Credit errors

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

```json
{
  "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](https://docs.screenshotlens.com/docs/dashboard/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.