Reference

Errors and troubleshooting.

Understand Browserherd API errors, WebSocket connection failures, retry behavior, and the fastest checks to perform before contacting support.

REST error format

Browserherd REST APIs return a JSON error object with a stable machine-readable code and a request ID for support.

JSON · ERROR RESPONSE

{
  "error": {
    "code": "CONCURRENCY_LIMIT_REACHED",
    "message": "Project concurrency limit reached.",
    "request_id": "req_7fc21a98",
    "docs_url": "https://docs.browserherd.com/errors#concurrency-limit-reached"
  }
}

HTTP status codes

Status	Code	Meaning and action
400	INVALID_REQUEST	The request body or query parameters are malformed. Validate types, allowed values, and required fields.
401	INVALID_API_KEY	The key is missing, malformed, expired, or revoked. Copy the active project key again from the dashboard.
403	PROJECT_ACCESS_DENIED	The key does not have permission for the requested project or capability.
404	SESSION_NOT_FOUND	The session ID does not exist, belongs to another project, or has passed its retention window.
409	CONCURRENCY_LIMIT_REACHED	All concurrent browser slots are in use. Wait for a session to close, add credits, or upgrade the plan.
422	INVALID_SESSION_CONFIG	A session option is recognized but invalid, such as an unsupported region or malformed viewport.
429	RATE_LIMITED	Too many API requests were sent in a short period. Retry with exponential backoff and jitter.
500	INTERNAL_ERROR	An unexpected service error occurred. Retry once, then provide the request ID to support.
503	CAPACITY_UNAVAILABLE	Capacity is temporarily unavailable in the requested region. Retry or select another region.
504	SESSION_START_TIMEOUT	The cloud browser did not become ready within the startup window. Retry the session.

WebSocket connection errors

A WebSocket upgrade can fail before Playwright or Puppeteer receives a browser connection. The client error may contain only the HTTP status and a short reason.

Close / HTTP code	Reason	Recommended action
401 / 4401	Authentication failed	Confirm the `token` query parameter and verify that the key has not been revoked.
403 / 4403	Project access denied	Use an API key issued by the project that owns the session or profile.
408 / 4408	Connection or session timed out	Reconnect and confirm that `sessionTTL` is long enough for the workflow.
409 / 4429	Concurrency unavailable	Close idle sessions or wait for capacity before reconnecting.
500 / 4500	Browser startup failed	Retry once. If the failure repeats, capture the timestamp, region, and request ID.

Common errors

Connection refused

Check these items in order:

The endpoint begins with wss://connect.browserherd.com.
The API key is present in the token query parameter and contains no extra spaces.
Your network and firewall permit outbound secure WebSocket connections on port 443.
The Browserherd status page does not show an active incident.

A Playwright or Puppeteer navigation timeout usually means the destination did not reach the selected wait condition. It does not necessarily mean the cloud browser failed.

await page.goto(url, {
  waitUntil: "domcontentloaded",
  timeout: 60_000
});

Use domcontentloaded instead of networkidle for pages that keep analytics, streaming, or long-polling requests open.

Session closed unexpectedly

Confirm the workflow did not exceed sessionTTL.
Check whether another part of the application called browser.close().
Inspect Browserherd History for the final session status and recorded events.
Use a longer TTL for long-running workflows, but still close the browser explicitly.

Concurrency limit reached

This error means the project already has the maximum number of active browsers allowed by its plan. Queue new work, close idle sessions, or increase concurrency.

Retry guidance

Error class	Retry?	Guidance
400, 401, 403, 422	No	Fix the request or credentials before trying again.
404	Usually no	Verify the resource ID and project.
409	Yes	Retry when a concurrency slot is expected to become available.
429	Yes	Use exponential backoff and honor `Retry-After` when present.
500, 503, 504	Yes	Retry a limited number of times with backoff; preserve the request ID if failures continue.

Contact support

When the error persists, email [email protected] with the request ID, timestamp, project name, region, client library and version, and a sanitized code sample. Never send your full API key.

Last updated September 18, 2026