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

# Errors

ScreenFramed error response format, common status codes, and retry guidance.

Errors use a consistent JSON envelope:

```json
{
  "error": {
    "code": "invalid_params",
    "message": "Invalid device. Must be one of: iphone-16-pro, macbook-pro-16, ipad-pro-m4, browser-macos, browser-windows"
  }
}
```

## Status codes

**Invalid request**

The API understood the request shape but rejected one or more parameters.

**Invalid API key or signature**

The request did not include valid authentication.

**Insufficient credits**

The render was not started because the account did not have enough credits.

**Forbidden scope**

Scoped keys can only call endpoints included in their scope list.

**Not found**

The requested resource was not found for the authenticated account.

**Rate limited**

Rate limits are account-plan dependent and reset continuously.

**Capture failed**

The request was valid, but the capture or composition could not complete.

## Retry strategy

| Failure | Retry? | Guidance |
|---|---|---|
| `429` | Yes | Respect `Retry-After` and use backoff. |
| Network interruption | Yes | Retry with jitter. Use idempotent request payloads. |
| `400` validation | No | Fix parameters first. |
| `401` / `403` | No | Fix key, signature, or scope. |
| `402` | No | Add credits or reduce job cost. |
| Target page timeout | Maybe | Retry once, then investigate page load conditions or use `async`. |

## Debug checklist

**Debug checklist**

**Inspect resolved parameters**

Add `show_resolved_params: true` while debugging composed requests.
  **Check target access**

Confirm the target URL is public unless you are using an auth profile.
  **Prefer deterministic selectors**

Use `selector` for deterministic element capture before trying natural-language element detection.
  **Queue slow pages**

Use `async: true` for slow dashboards and long full-page captures.