> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrnshot.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Status codes, response shapes, and how to handle each one

scrnshot uses standard HTTP status codes. Error bodies are JSON with at
least an `error` field:

```json theme={null}
{ "error": "human-readable message" }
```

## 400 — Bad request

The request body is malformed, `url` is missing, or an option isn't
permitted on your plan (e.g. `full_page: true` on Free). The message names
the specific problem:

```json theme={null}
{ "error": "full page screenshots are not available on the free plan" }
```

Fix the request — retrying unchanged will fail the same way. See
[Screenshot options](/guides/screenshot-options) for per-plan availability.

## 401 — Unauthorized

Missing, malformed, or revoked API key. Check that `X-API-Key` is set and
that the key hasn't been deleted from the dashboard.

```json theme={null}
{ "error": "unauthorized" }
```

## 402 — Quota exceeded

Your plan's monthly quota is exhausted.

```json theme={null}
{
  "error": "monthly quota exceeded",
  "plan": "free",
  "used": 100,
  "limit": 100,
  "resets_at": "2026-08-01T00:00:00Z"
}
```

Wait until `resets_at`, or upgrade to Pro for a higher ceiling
(`POST /v1/billing/checkout`). This is distinct from rate limiting below —
you can be well under your per-minute rate limit and still get `402` if
you've used up the month.

## 429 — Rate limited

You've exceeded the per-minute request rate for your plan (Free 5/min, Pro
60/min), or the demo endpoint's 5/day per-IP limit.

```json theme={null}
{
  "message": "Rate limit exceeded",
  "success": false,
  "limit": 5,
  "used": 5,
  "remaining": 0,
  "reset_time": 1755600000,
  "plan": "free"
}
```

`reset_time` is a Unix timestamp for when the window resets. Back off until
then — a tight retry loop will keep hitting `429`. If you're consistently
rate-limited on Pro, batch or queue requests client-side rather than firing
them concurrently.

## 5xx — Server error

Something failed on scrnshot's end (render failure, storage error,
timeout). These are safe to retry with backoff. If a `5xx` persists across
retries, check [status](https://scrnshot.site) or reach out — it isn't
something you can fix by changing the request.