Debug Errors

Validate and debug website screenshot processing errors

By default, error mode is turned off which means that the website screenshot API is robust and tolerant towards errors. There are two main types of errors that typically occurs, validation errors and processing errors.

With error mode turned on (e.g. error=true), a validation or processing error may occur if the screenshot request doesn't meet certain conditions. Enabling error mode is recommended when debugging or troubleshooting screenshots to understand how the screenshot is generated in case the output does meet the configuration criteria as explained in the examples below.

How to enable error mode

There are several ways to enable error mode.

Request Builder

Check the Error option under the Advanced tab.

GET Request

The example below shows a screenshot of a website with error mode enabled:

// Line breaks added for readability

POST Request

The example below shows a screenshot of a website with error mode enabled:


  "url": "",
  "error": true

Validation Errors (400 Bad Request)

A validation error denotes that the request is invalid due to an input or configuration error.

Example 1: Value Range

The image quality range is between 1 (lowest quality) to 100 (highest quality). If the request has a value outside of the expected range such as 110, the Screenshot API will adjust the quality to 100 automatically or raise an error when error mode is turned on.

Example 2: Viewport Size

The viewport area (screen size) also has a range depending on the subscription's plan. If the request specifies a value outside of the range such as 100000x100000 pixels, a default range such as 1920x1080 (HD 1080p) will be used or an error will be raised when error mode is turned on.

Why did the screenshot size not match the specified viewport size?
Enabling error mode will provide insight such as why a request with a viewport that is out of range such as 100000x100000 did not end up producing a 100000x100000 sized screenshot.

Example 3: Contradictory Settings

The full page screenshot setting denotes that screenshot of the entire webpage should be taken.

The section setting denotes that a screenshot of a specific section of the website should be taken.

Why was a full page screenshot created instead of a specific section?
With error mode disabled, a full page screenshot will be capture. With error mode enabled, an error will be raised stating that it isn't possible to take a full page screenshot and a screenshot of a section (partial webpage) at the same time.

Processing Errors (424 Failed Dependency)

A processing error denotes that an issue was detected with a dependency such as a missing element on the page.

Example 1: Missing Element

Let's say that the request would like to interact with the page such as hovering over an area, clicking on a menu item or a button, typing text into a textbox, scrolling to a specific section and more. By default, with error mode disabled, if the element such as a button to click on doesn't exit, the Screenshot API will still take a screenshot but the output may not have the desired outcome.

Enabling error mode will fail the request by raising an error when an element is missing. This can be desirable to ensure that screenshots meet the request criteria or fail if it doesn't.

Health Check Use Case

Let's say we have a mortgage interest rates webpage that we'd like to monitor daily using scheduled website screenshots by saving the screenshots to a cloud storage account.

In this sample use case, a healthy website can be determined if the page loaded successfully and an "interest rates" section appears on the website.

Enabling error mode will fail if the "interest rates" section doesn't exist, prompting investigation instead of assuming that the screenshots are valid every day even when the webpage content is in an unhealthy state.