ScreenshotMachine API Timeouts on Large Web Pages: Troubleshooting Steps

Short answer: ScreenshotMachine documents delay as the time its capture engine waits before taking a screenshot. For a full-length capture, it recommends considering a longer delay, such as 2000 ms or more. That setting is not documented as an HTTP or server-side timeout, and the API documentation does not publish a timeout threshold or timeout-specific error code. Check the request, compare viewport and full-page captures, inspect the returned image and X-Screenshotmachine-Response header, then contact support if the request still times out.

This guide follows the documented API behavior. See the ScreenshotMachine API documentation for current parameters and supported values.

1. Confirm the request and capture mode

ScreenshotMachine accepts an HTTP GET request to https://api.screenshotmachine.com. A customer key and target url are required. Percent-encode the target URL, especially when it contains query parameters or other reserved characters.

For a full-page screenshot, set dimension to a supported width and full, for example 1024xfull. Width can be 100–1920 pixels. Height can be 100–9999 pixels or full. Full-page captures can be very long, so first compare with a viewport-sized capture such as 1024x768. If the viewport capture succeeds but full-page capture does not, the full-page mode is a useful clue; this comparison is a diagnostic technique, not a vendor-prescribed timeout test.

2. Try a longer capture delay

The documented default delay is 200 ms. It controls how long the capture engine waits before creating the screenshot. The allowed values are 0, 200, 400, 600, 800, 1000, and 2000 through 10000 in 1000 ms increments.

ScreenshotMachine advises considering a value of 2000 ms or more for full-length screenshots because long pages may contain more images or animations. Increase the delay only as needed. A longer delay may give page content more time to appear, but the documentation does not say it extends an API request timeout or guarantees a fix.

3. Make a diagnostic request with cURL

Use a viewport capture first, then change the dimension to 1024xfull and set a longer delay. Save response headers separately so you can check for the documented error header.

curl -sS -G "https://api.screenshotmachine.com" \
  --data-urlencode "key=YOUR_CUSTOMER_KEY" \
  --data-urlencode "url=https://example.com/long-page" \
  --data-urlencode "dimension=1024xfull" \
  --data-urlencode "delay=2000" \
  --data-urlencode "format=png" \
  -D response-headers.txt \
  -o screenshot.png

# Inspect the response header, if present
# Linux:
grep -i '^X-Screenshotmachine-Response:' response-headers.txt
# macOS:
grep -i '^X-Screenshotmachine-Response:' response-headers.txt

Replace the example URL and key. If the command returns an image, verify that it is a real screenshot rather than an error image. The API can return an error image for invalid or incomplete calls.

4. Reproduce the request in Python

This example uses only the Python standard library. It records headers and writes the response body, so check the header and inspect the saved file before treating it as a successful capture.

from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

params = {
    "key": "YOUR_CUSTOMER_KEY",
    "url": "https://example.com/long-page",
    "dimension": "1024xfull",
    "delay": "2000",
    "format": "png",
}
request_url = "https://api.screenshotmachine.com/?" + urlencode(params)

try:
    request = Request(request_url, method="GET")
    # This is a client-side wait limit chosen by your application, not a
    # documented ScreenshotMachine server-side timeout value.
    with urlopen(request, timeout=90) as response:
        body = response.read()
        print("HTTP status:", response.status)
        print("ScreenshotMachine response:", response.headers.get(
            "X-Screenshotmachine-Response", "not present"
        ))
        with open("screenshot.png", "wb") as image_file:
            image_file.write(body)
except HTTPError as error:
    print("HTTP error:", error.code)
    print("ScreenshotMachine response:", error.headers.get(
        "X-Screenshotmachine-Response", "not present"
    ))
    print(error.read().decode("utf-8", errors="replace"))
except (TimeoutError, URLError) as error:
    print("Request did not complete:", error)

The 90-second value is an example of an application-side client timeout, not a ScreenshotMachine limit or recommendation. Choose a client timeout that suits your own job and request lifecycle; the vendor documentation reviewed here does not specify the appropriate value.

5. Reproduce the request in Node.js

Node’s built-in fetch does not supply a default request timeout. This example adds an application-side abort timer, checks the response header, and saves the returned bytes. The chosen 90 seconds is illustrative, not a documented ScreenshotMachine threshold.

import { writeFile } from "node:fs/promises";

const params = new URLSearchParams({
  key: "YOUR_CUSTOMER_KEY",
  url: "https://example.com/long-page",
  dimension: "1024xfull",
  delay: "2000",
  format: "png",
});

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 90_000);

try {
  const response = await fetch(
    `https://api.screenshotmachine.com/?${params}`,
    { signal: controller.signal },
  );
  console.log("HTTP status:", response.status);
  console.log(
    "ScreenshotMachine response:",
    response.headers.get("X-Screenshotmachine-Response") ?? "not present",
  );
  const bytes = Buffer.from(await response.arrayBuffer());
  await writeFile("screenshot.png", bytes);
} catch (error) {
  console.error("Request did not complete:", error);
} finally {
  clearTimeout(timer);
}

For older Node versions without global fetch, use an HTTP client available in your project and apply its documented timeout or abort mechanism. Do not interpret a local abort as proof that ScreenshotMachine returned a timeout error.

6. Read the response instead of assuming it timed out

For invalid or incomplete requests, ScreenshotMachine documents an error image and an X-Screenshotmachine-Response header containing an error code. Check both the header and body. The documented codes include:

Code	What to check
`invalid_hash`	Check the request’s hash construction if using a secret phrase.
`invalid_key`, `missing_key`	Confirm that the customer key is present and correct.
`invalid_url`, `missing_url`	Check URL encoding, the target URL, and whether the page requires authorization. The documented `invalid_url` description includes a 401 response for an authorization-required page.
`no_credits`	Check the account’s remaining credits or plan.
`invalid_selector`	If using a selector option, verify the selector against the target page.
`invalid_crop`	Check crop coordinates and dimensions.
`system_error`	Record the request details and response, then contact support if it persists.

The API documentation’s error list does not include a dedicated timeout code. A client-side timeout, network failure, error image, and valid screenshot are distinct outcomes; record which one you observed.

7. Troubleshooting checklist

Validate required fields. Send a customer key and a valid url; percent-encode the URL.
Check the dimensions. Keep width between 100 and 1920 pixels. For height, use 100–9999 or full.
Compare viewport and full-page captures. Keep the URL, key, and other settings the same, then change only the dimension. This helps isolate whether full-page capture is involved.
Increase delay deliberately. Try a documented value such as 2000 ms for a long page. It is a pre-capture wait, not a timeout override.
Inspect status, headers, and body. Look for X-Screenshotmachine-Response and check whether the body is an error image.
Record the failure before contacting support. Include the target URL, request parameters with the key redacted, client-side timeout setting, HTTP status, response header, and whether viewport mode worked. ScreenshotMachine lists support contact information.

8. Common errors and fixes

Symptom	Likely cause	Next step
Request fails immediately with an error image	Missing or invalid required field, invalid dimensions, or another documented request error	Read `X-Screenshotmachine-Response`; correct the corresponding key, URL, selector, crop, or credits issue.
Viewport succeeds, full-page request is slow or fails	The full-page capture is the differing request mode; large pages may have more content to render	Confirm dimension bounds, test `full` again with a documented longer delay, and provide the comparison to support if it persists.
Local script aborts, but no API error is visible	The client-side timeout expired before it received a completed response	Check network conditions and your own client timeout configuration. Do not describe that value as ScreenshotMachine’s server timeout.
Target page returns an access error	The page may require authorization; the API’s `invalid_url` description covers a 401 case	Check whether the target is accessible to the capture request and report the response details to support.
Increasing delay changes nothing	`delay` only controls the documented pre-capture wait and may not address the failure cause	Recheck request validity and diagnostics; escalate with the reproducible request details.
No timeout-specific response code	The documented error table does not define one	Preserve the client error, status, headers, and timing observed by your application; ask the vendor to classify it.

9. Performance, reliability, and cost considerations

Capture time: A larger full-page capture can take longer than a viewport capture. The documentation recommends considering a longer pre-capture delay for long pages, but does not promise that this prevents request timeouts.
Retries: The documentation reviewed here does not prescribe a timeout retry or backoff policy. Avoid tight automatic retry loops: they can add load and make diagnosis harder. If your application retries, use a bounded policy appropriate to your workload and distinguish completed error responses from requests that never completed.
Reliability claims: ScreenshotMachine’s pricing page lists a 99.99% availability SLA. That is a vendor-stated service term, not an independent uptime measurement; review the current terms before relying on it.
Billing: The pricing page describes billing in terms of fresh screenshots and says cached screenshots are not billed. Pricing and plan allowances can change, so check the current ScreenshotMachine pricing page before estimating cost. A slow response alone does not establish whether a capture was billed; consult account usage or support.

10. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. Its one-call API can return an image or PDF, with full-page capture and other capture options available. See the ScreenshotNeo API documentation for parameters and response details.

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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(({ writeFile }) =>
  writeFile('shot.webp', Buffer.from(await res.arrayBuffer()))
);

ScreenshotNeo removes cookie banners, 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.

FAQ

Does `delay=2000` set the API timeout to two seconds?

No. It makes the capture engine wait before creating the screenshot. It is not documented as a request timeout.

What is ScreenshotMachine’s maximum request duration?

The API documentation reviewed for this guide does not state a server-side or network timeout threshold.

Should I retry a timed-out request?

The reviewed documentation does not define a timeout-specific retry procedure. First determine whether the client aborted, an HTTP response arrived, or the API returned an error image and code. If you need a retry policy, keep it bounded and confirm billing behavior for your account.

Where can I ask ScreenshotMachine about a persistent timeout?

Use the contact details on its contact page and include a redacted reproducible request plus the observed response diagnostics.