Build your integration
Screenshot API errors, rate limits, and troubleshooting
Resolve ScreenshotEngine HTTP 400, 401, 429, 500, and 503 errors. Understand monthly quotas, retry behavior, blank captures, and output files.
View as MarkdownRecognize an error response
Successful captures return binary files. Errors return JSON, but the JSON shape depends on where the request failed. Check the HTTP status first, then inspect error, message, and any details fields. Do not assume every response has the same error properties.
{
"error": "Quota Exceeded",
"message": "You have reached your monthly screenshot limit."
}HTTP status codes and next steps
Use the response body to distinguish a temporary rate limit from a monthly quota limit. Both can return HTTP 429.
| Status | Likely cause | What to do |
|---|---|---|
| 400 | Missing or invalid parameters, unsupported values, or URL security validation. | Check field names and types. Use a public HTTP(S) URL; localhost and private network targets are blocked. |
| 401 | Invalid, missing, revoked, or origin-restricted API key. | Check your key and authentication method. POST uses a Bearer header; GET requires api_key. |
| 429 · rate limit | Too many requests within the request window. | Honor Retry-After when present. Reduce concurrency and add a bounded retry delay. |
| 429 · Quota Exceeded | Monthly screenshot allowance reached. | Check dashboard usage and your plan. Repeated immediate retries will not restore quota. |
| 500 | Navigation, rendering, element capture, or internal failure. | Check the target URL and selector. Retry a small number of times for transient failures; contact support if it persists. |
| 503 | The API is starting up or temporarily unavailable. | Wait a few seconds and retry with a capped backoff. |
Request limits and monthly allowances
Plans have a per-minute request limit and a monthly successful-capture allowance. The values below mirror the website’s plan configuration; check your dashboard for your account’s usage and billing details. Failed requests do not count toward the successful-capture allowance, but requests are still subject to rate limiting.
| Plan | Screenshots / month | Requests / minute |
|---|---|---|
| Free | 100 | 5 |
| Starter | 3,000 | 40 |
| Professional | 15,000 | 100 |
| Engine | 60,000 | 250 |
Choose a bounded retry strategy
For temporary 429 or 503 responses, respect Retry-After when present. Otherwise start with a short delay, increase it on each retry, add jitter, and cap the number of attempts. For example, make at most three retries with increasing delays.
Do not automatically retry invalid input, invalid credentials, or a monthly quota error. A client timeout can occur after a capture succeeds, so a retry can generate another successful request that counts toward usage.
Common capture problems
Blank or incomplete image: verify the target is publicly accessible, try a small waitFor delay, and use height: "full" for content below the fold. A site’s login screen or bot challenge is not bypassed by waiting longer.
Dark mode has no effect: the target website must implement a dark theme that responds to the browser’s color-scheme preference.
Unexpectedly old screenshot: use POST with cachePolicy: "no-cache". This bypasses the cache without updating old entries.
Image viewer cannot open the file: inspect the HTTP status and Content-Type. You may have saved an error JSON body with a .png extension.
An option has no effect: check GET versus POST field names. For example, send block_banners=true in a GET query, but blockBanners: true in a POST JSON body.
Still stuck: contact support with the request method, target URL, non-secret options, HTTP status, and approximate request time. Remove API keys before sharing requests or logs.