Errors

Errors are JSON with an error message; the create call’s 503 also has a code. A 429 or 502 from the edge in front of the API may not be JSON, so read the status first and parse the body defensively.

{ "error": "Insufficient balance" }

{ "error": "No eligible node found", "code": "browser_capacity_unavailable" }

Common bodies: 401 Unauthorized: Missing or invalid Authorization header or Unauthorized: Invalid token; 402 Insufficient balance; 403 Session limit reached (concurrency) or Extensions API is not enabled for this account; 400 names the field, for example Unsupported timezone "Europe/Berlin" for country US. or windowSize must be WIDTHxHEIGHT with width 320–16384 and height 200–16384. Unknown fields in a body are a 400 too.

Status codes

The dedicated-IP codes here (invalid_spec, dedicated_ip_not_owned, no_dedicated_ip, dedicated_ip_unhealthy) come back when proxyUrl names a dedicated:// address. The dashboard resolves the address before the create call, so Launch browser never returns them.

Status	Meaning	Retry?
`400`	Invalid or incompatible options, an unknown field on create, a missing `sessionId`, an update to an ended session, or a malformed dedicated IP spec (`code: invalid_spec`). The message names the problem.	No. Fix the request.
`401`	Missing or invalid API key.	No. Check `Authorization: Bearer …`.
`402`	The workspace is out of credits.	No. Add credits in the dashboard.
`403`	Concurrent-browser limit (`plan.concurrent_browsers` on `GET /v1/account/billing`; `starting` sessions count, a stop frees the slot as soon as it returns), a feature (extensions) the account isn’t enabled for, or a dedicated IP the workspace doesn’t own (`code: dedicated_ip_not_owned`).	Only after a session ends. Never in a loop.
`404`	Session, extension, pool, lease or account not found: unknown id, or one belonging to another workspace. On create, no dedicated IP matches the spec (`code: no_dedicated_ip`). Deleting an unknown profile isn’t a 404; it answers `{ "success": true }`.	No.
`409`	Browser pools only: a duplicate pool name, a size over the account’s warm-browser cap, an acquire that found nothing ready within `waitMs` (`No browser is currently ready in this pool`), an acquire on a paused pool, or a delete with active leases. See Browser pools.	Only the acquire one, as for `503`: back off, cap, then fall back to a plain create or report.
`429`	Too many requests, from the edge; the API itself doesn’t rate-limit today.	Yes: a few attempts, a couple of seconds apart and growing.
`502`	The edge couldn’t reach the API. Not JSON.	Once, after a couple of seconds.
`500`	Something failed on Driver’s side.	Once.
`503`	No browser capacity. Carries `Retry-After: 2` and `"code": "browser_capacity_unavailable"`. Or the session service is unavailable. With `code: dedicated_ip_unhealthy`, the dedicated IP failed its last health check: use another address.	Yes: back off with jitter, cap the attempts, then tell the user.
`504`	A machine was selected but Chrome wasn’t reachable before the startup deadline (20 s, up to 3 min on some machines).	Once.

Guidance for agents and automations

Never loop on 402 or 403. Surface the message; a person has to act.
503 is transient: start at the Retry-After of 2 seconds, grow with jitter, cap the attempts, then report. Retry 504 and 500 once.
After a 504 nothing is running; no stop call needed.
DELETE on an ended session still returns { "success": true }. A 404 means the id was never a session of this workspace.

Framework-side failures

Some failures show up in the framework, not as an HTTP status:

Symptom	Likely cause
`Target closed` / `Browser closed` mid-run	The session reached its `duration`, or was stopped from the dashboard. Check `GET /v1/browser/session`.
Connection refused on `cdpUrl`	The session isn’t `active` yet or has ended.
The site shows a challenge or block page	Framework fingerprint or automation tactics. Switch to Patchright and remove CDP hooks; then escalate: `type: "hosted_stealth"`, `"hosted_privacy"`, `captchaSolver: true`, and finally a person through the live view.
`net::ERR_SOCKS_CONNECTION_FAILED` on every navigation	The session’s egress isn’t reachable. Stop it and create another, in a different country if it persists; report it if it keeps happening.

Start

Browser sessions

Session options

Frameworks

Account

Status codes

Guidance for agents and automations

Framework-side failures

​Status codes

​Guidance for agents and automations

​Framework-side failures

Status codes

Guidance for agents and automations

Framework-side failures