BrowserCat API rate limits: what to do when requests fail

Short answer: BrowserCat’s public materials reviewed for this guide do not specify a numeric API request rate limit, burst allowance, or throttle and retry contract. A documented reason requests may be rejected is reaching an account’s hard spending limit without approving an increase. Check account usage and billing, BrowserCat’s live status page, and your connection setup before treating a failure as rate limiting.

BrowserCat lists concurrent request capacity on its pricing page, but that figure is not a requests-per-second or requests-per-minute limit. The reviewed sources also do not establish a BrowserCat-specific HTTP 429 response, Retry-After header, or fixed retry interval. [BrowserCat FAQ] [BrowserCat pricing]

1. First identify where the request failed

Separate connection setup failures from errors that occur after a browser session starts. A rejected WebSocket connection, a browser automation error, and an account billing block can look similar from an application’s perspective, but they call for different checks.

For each failure, record:

Timestamp and the endpoint or operation involved.
Whether the failure happened while opening the WebSocket connection or after a browser session began.
The actual client error and, when available, response status and body.
Whether other requests from the account also fail.
Recent account usage and billing state.

Keep API keys out of logs, issue reports, and support messages. This is a practical diagnostic checklist, not a BrowserCat-published error taxonomy.

2. Check account usage and billing

BrowserCat documents a dynamic soft and hard spending limit. After an account crosses its soft limit, BrowserCat asks the account holder to approve an incremental increase. If the increase is not approved and the hard limit is reached, BrowserCat says it will reject requests until the billing period ends or the limit is increased. That is an account spending-limit block; the FAQ does not describe it as API rate throttling. [BrowserCat FAQ]

Open your BrowserCat dashboard and review usage and billing.
Look for a spending-limit notice or a pending request to approve an increase.
If the hard limit has been reached, follow the account prompt to approve an increase or wait for the billing period to end.
Retry a small request after the account state is resolved and note whether the error changes.

The FAQ gives example limit defaults, but account terms can vary and vendor pricing can change. Check the current dashboard and FAQ for the limits that apply to your account rather than relying on a figure copied into a script or runbook. [BrowserCat FAQ]

3. Check BrowserCat service status

Inspect the live BrowserCat status page during an incident. It reports Browser Fleet (Websocket API) and Utility Endpoints (REST API) separately, so check the component that matches the failing operation. A status snapshot from an earlier date is not evidence of current availability. [BrowserCat status]

If the relevant component is reporting an incident, avoid treating repeated retries as a fix. Keep the failure details and retry after the status page indicates recovery.

4. Verify the Playwright connection

BrowserCat’s quick start shows Playwright connecting to wss://api.browsercat.com/connect with an Api-Key header. It recommends Playwright and points users to the dashboard for monitoring usage and billing. Compare your connection against the current guide if the WebSocket fails to open. [BrowserCat quick start]

import { chromium } from "playwright";

const apiKey = process.env.BROWSERCAT_API_KEY;
if (!apiKey) {
  throw new Error("Set BROWSERCAT_API_KEY before running this script.");
}

const browser = await chromium.connectOverCDP(
  "wss://api.browsercat.com/connect",
  {
    headers: { "Api-Key": apiKey },
  }
);

try {
  const page = await browser.newPage();
  await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
  console.log(await page.title());
} finally {
  await browser.close();
}

Run it with the Playwright package installed and the key supplied through the environment. Do not print the key while debugging. Confirm the endpoint and header spelling against BrowserCat’s current quick start before deploying changes.

5. Use safe retry behavior while diagnosing

The reviewed BrowserCat sources do not publish a retry schedule or guarantee that a particular response means “rate limited.” Do not hard-code a BrowserCat-specific 429 interpretation, Retry-After handling, or fixed delay based on assumptions.

For your own client, a conservative general-purpose approach is to:

Retry only operations that are safe to repeat.
Use a small, bounded number of attempts with increasing delays and random jitter, as an application-level precaution rather than BrowserCat guidance.
Stop retrying when the account is blocked or a service incident is active; repeated attempts will not resolve those conditions.
Log the attempt count, timestamp, endpoint, and error details without secrets.
Preserve the original error if retries are exhausted, so the calling service can classify it.

6. Distinguish concurrency from rate limits

BrowserCat’s pricing page lists concurrent request capacity for plans. Concurrency describes work in progress at once; it does not by itself define how many requests may begin per second or minute, a burst allowance, or a universal throttle response. The reviewed public sources do not specify those rate-limit details. If your workload depends on a precise admission rate, ask BrowserCat support for the current account-specific limits. [BrowserCat pricing]

7. Troubleshooting checklist

Symptom	What to check	Next step
Requests begin failing after usage rises	Account usage, billing period, and soft or hard spending-limit notices	Resolve the account limit in the dashboard or wait for the billing period to end. [FAQ]
WebSocket connection fails immediately	Endpoint, `Api-Key` header, key validity, and service status	Compare with the current quick start and check Browser Fleet status. [Quick start] [Status]
Connection opens but browser work fails	The specific browser operation and its error; whether the failure is reproducible	Capture the details without secrets and consult the relevant client and BrowserCat documentation. The reviewed sources do not define a universal error mapping.
Several unrelated requests fail at once	Account state and the live status page	Check both before increasing retries. [FAQ] [Status]
You suspect a 429 or retry header	The actual response from your request and current BrowserCat documentation	Do not assume a status code, header, or retry interval that the reviewed public sources do not document.

8. Performance, reliability, and cost considerations

Performance: More concurrent work can increase throughput only when the plan and workload support it; the published concurrency figure does not establish a request start rate. Measure your own queue time and session duration.
Reliability: Check account health and live component status before adding retry volume. Bound retries and preserve diagnostic context so a persistent failure does not become a retry loop.
Cost: BrowserCat says successful Utility API calls consume one credit each. Its spending-limit behavior makes usage and billing checks relevant when requests are rejected. Verify current plan terms in the dashboard and pricing page. [BrowserCat FAQ] [BrowserCat pricing]
Client choice: BrowserCat supports Playwright, Puppeteer, and CDP-based clients. Its sources recommend Playwright, but do not promise that changing client libraries resolves an API rejection. [Quick start] [BrowserCat]

9. If the failure remains unexplained

Send BrowserCat support the timestamp, endpoint, whether the failure occurred during connection setup or browser work, the status and response body if present, and the relevant account usage and status-page findings. Redact the API key and any sensitive request data. Ask directly whether your account has an applicable request-rate or concurrency limit and what response or retry behavior is currently supported.

Or skip the browser setup

If your goal is to capture a website screenshot rather than operate a remote browser session, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF. Its cookie and consent handling removes known banners, newsletter popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. An 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.

cURL:

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

Python:

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)

Node.js:

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 Bun.write("shot.webp", res);

See the ScreenshotNeo API documentation, then sign up free for 1,000 screenshots a month with no card.

FAQ

Does BrowserCat publish a numeric API rate limit?

The public materials reviewed for this guide do not specify a numeric requests-per-second or requests-per-minute limit.

Does BrowserCat’s concurrent request figure mean requests per second?

No. The pricing page lists concurrent capacity; it does not define a request start rate or burst allowance.

Is a hard spending-limit block the same as rate limiting?

The FAQ documents it as a billing limit that can cause requests to be rejected. It does not equate that condition with API throttling.

Which client should I use?

BrowserCat’s quick start recommends Playwright. Its materials also support Puppeteer and CDP-based clients; changing libraries is not documented as a fix for rejected requests.