BrowserCat Screenshot API Timeout: Common Causes and Fixes

A “BrowserCat screenshot API timeout” can mean several different things: a timeout connecting to BrowserCat’s hosted browser, a navigation or page-readiness wait that does not finish, a screenshot action that takes too long, or your own client giving up while waiting for the result. Identify which stage expired before changing a timeout.

BrowserCat’s documented approach is to connect to a hosted browser with Playwright and capture with Playwright’s page.screenshot(). The documentation reviewed does not establish a dedicated BrowserCat screenshot REST endpoint. Check the endpoint and exception in your code before treating the problem as a BrowserCat screenshot API error. See the BrowserCat quick start, Playwright guide, and JavaScript and TypeScript cheatsheet.

1. Identify which stage timed out

A screenshot is the end of a sequence. Each stage can have its own deadline, and a caller-side HTTP timeout can expire even while the browser is still working.

Stage	What is waiting	What to inspect
Connection	Your client establishing a BrowserCat browser session	Whether the WebSocket connection completed; endpoint, credentials, and network errors
Navigation	The browser loading the target after goto	Navigation wait condition and navigation timeout
Readiness	A load state, locator, selector, or explicit delay	Whether the chosen condition can become true on this page
Screenshot action	Playwright producing the screenshot	The exception location, page state, and screenshot options
Caller response	Your application waiting for the browser workflow or remote service	HTTP/client deadline, job deadline, and elapsed time outside the browser

Record the exact client library and version, BrowserCat connection endpoint, target URL, Playwright call, elapsed time, and full exception text. Remove API keys, cookies, authorization headers, and other secrets before sharing logs. An error before the browser connection completes is not a page screenshot timeout.

2. Run a minimal BrowserCat Playwright capture

This JavaScript example follows BrowserCat’s documented hosted-browser connection pattern and takes the screenshot with Playwright. Set BROWSERCAT_API_KEY in your environment and replace the target URL. Install the dependencies in a Node.js project with npm install playwright.

import { chromium } from 'playwright';

const apiKey = process.env.BROWSERCAT_API_KEY;
if (!apiKey) throw new Error('Set BROWSERCAT_API_KEY first');

const browser = await chromium.connectOverCDP(
  `wss://api.browsercat.com/connect?apiKey=${encodeURIComponent(apiKey)}`
);

try {
  const context = await browser.newContext();
  const page = await context.newPage();

  // Navigation completion and content readiness are separate decisions.
  await page.goto('https://example.com', {
    waitUntil: 'domcontentloaded',
    timeout: 30_000
  });
  await page.locator('h1').waitFor({ state: 'visible', timeout: 10_000 });
  await page.screenshot({ path: 'screenshot.png', fullPage: true, timeout: 30_000 });
} finally {
  await browser.close();
}

Use the connection method and authentication format shown in the current BrowserCat guide for the Playwright version and runtime you have installed. The sample illustrates separate navigation, locator, and screenshot deadlines; it does not establish a BrowserCat service-side timeout or universal limit. If your documented integration uses a different Playwright connection call, retain that call and apply the same staged diagnosis.

3. Choose a readiness condition that matches the page

Navigation completion does not always mean the content you need is ready. Conversely, waiting for all network activity to stop can be a poor fit for pages with polling, analytics, chat, or other persistent requests. BrowserCat’s examples show navigation wait states such as domcontentloaded and NetworkIdle; choose based on the page and verify that the condition can complete.

Wait for a stable element when possible

If the screenshot needs a particular chart, headline, or result panel, wait for that element rather than an unnecessarily broad condition:

await page.goto('https://example.com/report', {
  waitUntil: 'domcontentloaded',
  timeout: 30_000
});
await page.locator('[data-report-ready="true"]').waitFor({
  state: 'visible',
  timeout: 15_000
});
await page.screenshot({ path: 'report.png', fullPage: true });

Choose a selector that is stable and represents content being ready, not a transient animation or an element that may never appear for some users. If there is no reliable marker, use an appropriate navigation state and a bounded delay only when the page has a known delayed update. A longer timeout cannot make a condition that never becomes true succeed.

Configure the timeout for the stage that is slow

BrowserCat’s JavaScript cheatsheet documents navigation timeout configuration, and Playwright also has action and expectation waits. Keep those deadlines intentional and distinct. For example, a navigation timeout does not necessarily change a locator wait or your application’s outer request deadline. Check the relevant Playwright API for the exact call and installed version.

// Example: configure navigation and locator waits independently.
page.setDefaultNavigationTimeout(30_000);
page.setDefaultTimeout(10_000);

await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
await page.locator('main').waitFor({ state: 'visible' });

Do not copy timeout defaults, error names, or service limits from another screenshot provider and assume they apply to BrowserCat. The available BrowserCat references do not verify a BrowserCat-specific timeout error taxonomy, service-side deadline, or retry rule.

4. Diagnose the target and the surrounding client

1. Reproduce with a simple reachable page. If that works but one target fails, investigate the target’s response, redirects, scripts, access requirements, and ongoing network activity. These are possible causes to check, not conclusions about your specific page.
2. Separate connection from page work. Log when the BrowserCat session connects, when navigation begins and ends, when the readiness wait resolves, and when the screenshot call begins and ends.
3. Check every deadline. Compare measured elapsed time with BrowserCat connection setup, Playwright navigation/action/expectation waits, and the caller’s own HTTP or job deadline.
4. Reduce the reproduction. Keep one URL, one navigation, one readiness condition, and one screenshot call. Add options back one at a time.
5. Review browser configuration only when evidence points there. BrowserCat documents a BrowserCat-Opts header and query parameters for options such as region and browser choice. The configuration guide does not identify these as timeout fixes; inspect them only if session configuration or routing appears relevant.
6. Escalate with a safe reproduction. Preserve the exact exception and timestamps, redact credentials and personal data, and consult current BrowserCat documentation or support if the failing stage remains unclear.

5. Common timeout symptoms and fixes

Symptom	Likely area	What to do
Failure occurs before a page object is available	Connection or session setup	Confirm the documented endpoint and credentials, capture the connection exception, and check whether the connection actually completed.
goto throws before the screenshot call	Navigation deadline or target response	Inspect the target and redirects, select a suitable navigation wait state, and adjust the navigation timeout only if measured navigation needs more time.
A locator or expectation wait expires	Readiness condition	Verify the selector exists for this page and state; wait for a stable content marker or choose another bounded readiness strategy.
Navigation finishes but the screenshot call fails	Screenshot action or page state	Read the stack trace to confirm the failing call, simplify screenshot options, and check the action deadline separately.
Browser work appears to finish but the caller reports timeout	Outer HTTP/client or job deadline	Measure time on both sides, inspect the caller’s deadline, and avoid letting it expire before the expected browser operation can return.
Only a complex target fails; a simple page works	Target-specific behavior	Check redirects, access requirements, long-running scripts, persistent requests, and whether the expected content marker is present.
Increasing a timeout changes nothing	Wrong timeout or non-timeout failure	Locate the exact exception and stage first; an unreachable target or never-satisfied condition is not repaired by a larger unrelated timeout.

6. Reliability, performance, and cost considerations

Longer waits can make slow pages more likely to finish, but they also increase the time each failed or delayed capture holds a browser session and delays the caller. Prefer a readiness condition tied to the desired content, keep waits bounded, and measure stage durations. This makes slow navigation distinguishable from slow content and caller-side latency.

For reliability, capture enough timing and exception detail to identify the failing stage, and retry only after diagnosing whether the failure is transient and whether repeating the operation is appropriate for your workflow. The reviewed BrowserCat documentation does not provide a verified fixed retry count or a BrowserCat-specific timeout recovery policy, so do not assume one. For cost, consult your current BrowserCat account terms and plan details; the research available here does not establish BrowserCat pricing or whether timed-out work is billed.

7. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. For a one-request capture, use its API instead of maintaining the hosted-browser connection and Playwright capture flow. 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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
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(fs => fs.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, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.

8. FAQ

Does BrowserCat provide a screenshot REST API?

The official material reviewed documents a hosted browser used through Playwright, with screenshots taken through Playwright page methods. It does not establish a dedicated screenshot REST endpoint. Confirm the endpoint in the integration you are using.

Should I always wait for network idle before capturing?

No. Network idle is one possible wait state, but pages with persistent network activity may not reach it. A stable locator for the content you need can be a more specific readiness signal.

What BrowserCat timeout value should I use?

There is no verified universal BrowserCat timeout value in the reviewed references. Measure the slow stage, configure that stage’s deadline, and check your outer caller deadline too.

Is ScreenshotOne’s timeout_error a BrowserCat error?

No. That name and its associated guidance are specific to ScreenshotOne. Use the actual exception and current BrowserCat documentation to diagnose a BrowserCat workflow.