Error Handling

All errors return JSON with a consistent structure:

{
  "error": "error_code",
  "message": "Human-readable description",
  "status": 400,
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Use request_id when contacting support — it helps us find your request in logs.

Error codes

Code	HTTP Status	Meaning
`validation_error`	400	One or more parameters are invalid. Check `details` field.
`invalid_url`	400	The `url` parameter is not a valid HTTP/HTTPS URL.
`dimension_exceeded`	400	Width/height exceeds your plan's maximum.
`unauthorized`	401	Missing or invalid API key.
`plan_required`	403	Feature requires a higher plan. See `required_plan` field.
`ip_not_allowed`	403	Request IP is not in the IP whitelist.
`rate_limited`	429	Per-minute rate limit exceeded. See `retry_after`.
`quota_exceeded`	429	Monthly quota used up. Upgrade your plan.
`template_not_found`	404	The requested OG template ID doesn't exist.
`screenshot_failed`	502	Playwright failed to load or render the page.
`timeout`	504	Screenshot took longer than 30 seconds.
`internal_error`	500	Unexpected server error.

Validation errors

When parameters are invalid, we return details:

{
  "error": "validation_error",
  "message": "Request validation failed",
  "details": [
    { "field": "width", "message": "Number must be less than or equal to 3840" },
    { "field": "url", "message": "Invalid url" }
  ],
  "status": 400
}

Screenshot failures (502)

A 502 usually means the target website was unreachable, took too long to load, or triggered a security challenge (Cloudflare, etc.).

Common causes:

The target URL requires authentication or CAPTCHA
The site is down or unreachable from our servers
The page takes longer than 30s to load → use a shorter wait_until value

Try wait_until=domcontentloaded instead of networkidle for fast captures of slow sites.

Plan required (403)

When you use a feature that requires a higher plan:

{
  "error": "plan_required",
  "message": "Stealth mode requires Growth plan or above",
  "required_plan": "growth",
  "status": 403
}

See the full feature matrix for what each plan includes.

Debugging tips

Check the request_id header in the response
Try the same URL in the Playground to see the full error
Use cache=false to bypass cached results during debugging
Test with https://example.com to verify your API key works
If you get 403 plan_required, check rate limits & plans for feature availability
If you get 403 ip_not_allowed, check your IP whitelist settings