Timeout Error

It is an API error returned when the API can’t render screenshots or video within the specified timeout:

{
  "is_successful": false,
  "error_code": "timeout_error",
  "error_message": "The screenshot couldn't be taken within the specified timeout. Either the site doesn't respond quickly, or rendering takes longer than expected. Play with the `timeout` or the `navigation_timeout` options or reach the support for the investigation.",
  "documentation_url": "https://screenshotone.com/docs/errors/"
}

Reasons and how to fix

Let’s quickly consider possible reasons and possible solutions.

Timeout is too small

By default, the timeout is about 60 seconds. You must fit your rendering request within that timeout.

You can:

Either use asynchronous requests and webhooks to get the results. And set the timeout up to 600 seconds. Or you can try to increase the timeout up to 90 seconds.

The element for wait_for_selector didn’t appear

If the request waits for wait_for_selector and the element doesn’t appear, the error message says so:

{
  "is_successful": false,
  "error_code": "timeout_error",
  "error_message": "The element for the `wait_for_selector` option didn't appear on the page within 90 seconds. Check the selector, or allow more time with the `timeout` option: up to 90 seconds, or up to 600 seconds for asynchronous requests.",
  "documentation_url": "https://screenshotone.com/docs/errors/timeout/"
}

The API waits for the element for as long as the request’s timeout allows, or up to 60 seconds if you don’t set timeout. It doesn’t load the page a second time after that wait.

You can:

1. Check the selector: make sure it matches an element that the page adds without user interaction.
2. Increase the timeout: if the element needs more time, set timeout up to 90 seconds, or up to 600 seconds for asynchronous requests.

A very long page with full_page

With full_page, the API scrolls to the bottom of the page and back before taking the screenshot, so that lazy-loaded images and sections load. On very long pages, scrolling alone can take most of the timeout.

You can:

1. Allow more time: increase timeout up to 90 seconds, or use asynchronous requests with a timeout up to 600 seconds.
2. Limit the height: if you only need the top of the page, set full_page_max_height.
3. Scroll faster: lower full_page_scroll_delay (400 milliseconds by default) or raise full_page_scroll_by (the viewport height by default). Scrolling too fast can leave lazy-loaded images unloaded.
4. Skip scrolling: if the page has no lazy-loaded content, set full_page_scroll to false.

The browser can’t capture a page much taller than about 130,000 pixels at full height, however long it waits. For such pages, set full_page_max_height.

Delay is too big

Make sure that your delay is not too big, e.g. if you set it to 30 seconds, and it takes the website to load for 30 seconds, it is better to decrease the delay.

A website is not loading properly

Some sites just take too much time to load or they don’t emit DOMContentLoaded events.

Try to play with different values of the wait_until option and see if it helps.

Retrying with a proxy

A proxy is not the first fix for timeout_error. First try to reduce the page weight, decrease delay, adjust timeout or navigation_timeout, or use asynchronous requests and webhooks.

Retrying once with a proxy can help when the timeout looks like IP-based throttling, regional routing, or a page that stalls only from ScreenshotOne’s default IP range. Only do this for targets where automated access is allowed.

See when to retry with a proxy for the full retry matrix and a code example.

Long duration of the video

Often when you record a video of a long duration, the API must not respond in time. Since it takes to both record a video and stream it.

Try to decrease the video duration you are recording, it might help.

Reach out to support

If nothing helps you, please, reach out to support@screenshotone.com and we will try to help you as fast as possible.