How to Fix ScreenshotOne Timeout Errors on Slow Websites

To fix a ScreenshotOne timeout_error on a slow website, first identify whether the target is slow to respond, the page needs more rendering time, or your own client is giving up too soon. Remove unnecessary fixed delays, choose a wait condition that fits the page, and tune navigation_timeout or timeout for the stage that is stalling. If the job may exceed the synchronous window, use an asynchronous request with a webhook.

ScreenshotOne defines timeout_error as a capture that could not finish rendering within its allowed timeout. Its documentation says either the site may not respond quickly or rendering may take longer than expected. The settings below are vendor-documented limits, not a guarantee that every site will render within them. ScreenshotOne timeout error guidance · ScreenshotOne request options.

1. Identify which timeout you are hitting

ScreenshotOne has distinct timeout settings. The overall timeout is the rendering budget for the request. navigation_timeout is the maximum wait for the target site to respond during navigation.

Setting or symptom	What it controls or suggests	Documented value
timeout	Overall time allowed for the screenshot rendering request	60 seconds default; 90 seconds maximum for regular requests
navigation_timeout	Wait for the target site to respond during navigation	30 seconds default and maximum
delay	Extra fixed wait before capture; this consumes elapsed request time	0 seconds default
Async request with webhook	For work that may exceed a synchronous request window	Timeout values up to 300 seconds, as described in the error guidance
request_aborted or caller timeout	Your HTTP client, serverless function, or proxy stopped waiting	Depends on your caller’s configuration

These values come from ScreenshotOne’s current documentation. A navigation timeout points toward slow response or navigation; an overall timeout can also mean rendering itself is expensive. Check the returned error and the timeout configured in your caller before changing several settings at once.

2. Apply the smallest relevant fix

1. Remove excessive delay. A fixed delay is added to the elapsed time even if the page is already ready. Start with the default of zero unless the page demonstrably needs extra time for content to appear. See the timeout guide.
2. Choose a wait condition for the page. The documented wait_until values are load, domcontentloaded, networkidle0, and networkidle2; the options reference gives load as the default. A page with ongoing requests may never become idle, so network-idle waits can make matters worse. Try another condition when the current one stalls. Rendering performance guidance.
3. Increase the timeout for the failing phase. Raise timeout when rendering needs more total time, within the request-mode limit. Adjust navigation_timeout only when navigation response is the bottleneck; its documented maximum is 30 seconds.
4. Use async processing for long jobs. ScreenshotOne’s timeout guide describes asynchronous requests with webhooks and timeout values up to 300 seconds. Configure your webhook receiver and caller for the asynchronous flow rather than keeping a short-lived synchronous connection open.
5. Check the caller’s own deadline. An HTTP client, load balancer, or serverless function may abort before ScreenshotOne’s configured timeout. Set the caller’s wait budget to accommodate the intended request mode, or handle the work asynchronously. ScreenshotOne discusses caller aborts in its API error handling guide.

3. Runnable request examples

Replace YOUR_ACCESS_KEY and the example URL with your values. Keep the initial diagnosis focused: use no extra delay, select a wait condition suitable for the site, and increase the overall timeout only as needed. The exact option names and accepted values are documented in ScreenshotOne’s request options.

cURL

curl -G 'https://api.screenshotone.com/take' \
  --data-urlencode 'access_key=YOUR_ACCESS_KEY' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'wait_until=domcontentloaded' \
  --data-urlencode 'timeout=90000' \
  --data-urlencode 'navigation_timeout=30000' \
  -o screenshot.png

Python

import requests

params = {
    "access_key": "YOUR_ACCESS_KEY",
    "url": "https://example.com",
    "wait_until": "domcontentloaded",
    "timeout": 90000,
    "navigation_timeout": 30000,
}
response = requests.get(
    "https://api.screenshotone.com/take",
    params=params,
    timeout=110,
)
response.raise_for_status()
with open("screenshot.png", "wb") as screenshot:
    screenshot.write(response.content)

Node.js

const params = new URLSearchParams({
  access_key: 'YOUR_ACCESS_KEY',
  url: 'https://example.com',
  wait_until: 'domcontentloaded',
  timeout: '90000',
  navigation_timeout: '30000',
});

const response = await fetch(
  `https://api.screenshotone.com/take?${params}`,
  { signal: AbortSignal.timeout(110_000) }
);
if (!response.ok) {
  throw new Error(`ScreenshotOne returned HTTP ${response.status}: ${await response.text()}`);
}
const image = new Uint8Array(await response.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('screenshot.png', image));

The examples use a 90-second ScreenshotOne overall timeout and give the caller slightly more time to receive the response. ScreenshotOne’s documented regular-request maximum is 90 seconds; a longer caller timeout does not raise that API limit.

4. Special cases: async work, proxies, and full-page capture

When synchronous requests are not enough

If capture duration may exceed the synchronous window, use ScreenshotOne’s asynchronous request flow and webhook. Its timeout guide documents values up to 300 seconds for async requests. Ensure your webhook endpoint can receive the completion event and that your own job scheduler does not discard the pending task. Follow the current vendor instructions for the exact asynchronous parameters and signature handling: Timeout Error.

When a proxy is worth one retry

A proxy may help when evidence suggests IP throttling, blocking, or regional routing trouble. It is not a general-purpose timeout fix: proxy routing can add latency and another service dependency. First reduce page work, tune the wait and timeout settings, or move to async. Consider a single proxy retry only when the symptoms point to routing or IP restrictions, and only where automated access is allowed. See ScreenshotOne’s proxy guide and error handling guide.

When full-page capture is involved

Full-page screenshots can require additional page work. ScreenshotOne documents a default full-page algorithm and a by_sections alternative, along with scroll controls, motion reduction, and extra rendering wait options. Begin with the default behavior; change a full-page setting only when you observe a specific rendering problem. More rendering work can reduce performance. Details: Full-page screenshots.

5. Troubleshooting by symptom

Symptom	Likely cause	What to try
timeout_error appears quickly	Navigation is not receiving a timely response, or selected wait condition is unsuitable	Try domcontentloaded or another documented wait_until value; inspect whether navigation is the stalled phase.
It fails after a long, predictable interval	Overall timeout is exhausted; an unnecessary delay may be using part of the budget	Remove fixed delay, then increase timeout within the request-mode limit if rendering needs it.
It times out only with networkidle0 or networkidle2	Persistent network activity prevents the page from satisfying the idle condition	Try load or domcontentloaded instead.
ScreenshotOne allows more time, but your app still fails	Your HTTP client, proxy, serverless runtime, or job runner aborts first	Align the caller deadline with the request budget, or use asynchronous handling. Check whether the error is a caller-side abort.
Only full-page captures time out	Full-page rendering adds work or a quality adjustment is slowing capture	Start with the default algorithm and remove unneeded scroll or rendering adjustments; test by_sections only if it addresses an observed issue.
Failures appear tied to a particular region or source IP	Possible routing issue, throttling, or blocking	After the basic timeout fixes, try a targeted proxy retry if permitted. Do not proxy every request by default.
Every wait setting fails for one target	The site may be unusually slow, unavailable to automated access, or expensive to render	Check the target independently, reduce capture work, use async if appropriate, and share the failing URL and request details with ScreenshotOne support.

6. Performance, reliability, and cost considerations

• Performance: A shorter wait condition and removal of arbitrary delay can reduce avoidable waiting. Full-page rendering and additional quality adjustments can add work, so enable them only for a demonstrated need. ScreenshotOne publishes qualitative performance guidance but the cited material does not establish a universal speed benchmark.
• Reliability: Treat navigation, rendering, and caller deadlines as separate failure points. An async job with a webhook is a better fit when completion time is unpredictable. A proxy is a conditional recovery path, not a substitute for diagnosing the slow phase.
• Retries: Retry selectively after changing a likely cause. Repeating the same request with the same wait and deadline is unlikely to address a deterministic timeout, and can create excess traffic to the target.
• Cost: The referenced ScreenshotOne documentation does not establish a universal per-timeout charge or pricing consequence. Check your account’s current plan and billing terms rather than assuming that a timed-out attempt is free.

7. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF, and its parameter names used by other screenshot APIs also work, which can make switching easier. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up free and get 1,000 screenshots a month with no card.

FAQ

Does increasing timeout fix every timeout_error?

No. The failure may be navigation, rendering, an unsuitable wait condition, or your caller aborting first. Identify the phase before increasing the overall budget.

Should I always use networkidle0 for slow websites?

No. Pages with persistent network activity may not become idle. Try the condition that matches the page’s behavior; the documented choices include load, domcontentloaded, networkidle0, and networkidle2.

Can a proxy guarantee the capture will succeed?

No. A proxy is a targeted attempt for plausible IP or regional routing problems and can add latency. It cannot fix slow rendering or an overly short caller deadline.

What is the maximum timeout?

ScreenshotOne’s options reference documents a 90-second maximum overall timeout for regular requests; its timeout guidance describes up to 300 seconds for asynchronous requests with webhooks. The documented navigation timeout maximum is 30 seconds.