Appearance

Limits and errors Beta ​

Concurrency, timeouts, API errors and connection close codes.

Limits ​

LimitValue
Browsers at once5 per account. A session counts from its creation, including the 45 seconds before you connect.
connect_urlOne connection, within 45 seconds of creating the browser.
Session length1 hour at most. Set a shorter one with timeout_sec (10 to 3600 seconds).
Idle time5 minutes without a CDP message from your client by default. Change it with idle_timeout_sec (10 to 3600 seconds).
TrafficNo cap by default. Set one with max_mb.
BalanceStarting a session needs a minimum balance.

How a session ends ​

A session is pending once created. It becomes running when your client connects within 45 seconds, and ended when the client closes or disconnects or a limit is reached. Cancelling a pending session ends it. If nobody connects within 45 seconds, its connect_url expires and it stays pending, without counting toward the limit.SESSION STATESPOST /v1/browserspendingunused for 45 s: expires,not billedconnectwithin 45 srunningclose, disconnector a limitendedbilled by trafficDELETE /v1/browsers/{id}: cancelled, not billed

A session ends, and is billed, when the first of these happens:

  • your client closes the browser (browser.close()) or disconnects,
  • it reaches its session length, idle time or traffic cap,
  • the browser stops on its own.

Ending the connection ends the session: there is no session to stop afterwards. To cancel a browser you created but haven't connected to, call DELETE /v1/browsers/{id}. A running session can't be stopped through the API (the call answers 409); close it from your client.

API errors ​

POST /v1/browsers and the other endpoints answer with these errors:

StatusWhenWhat to do
400An invalid parameter. The message names it.Fix the parameter. See Parameters and API.
401A missing or wrong API key.Check api_key.
403Your email address isn't verified yet.Follow the link in the verification email.
402Your balance is too low to start a session.Top up on the dashboard.
404The browser doesn't exist, or the Hosted Browser isn't enabled on your account.During the beta, write to [email protected].
409DELETE on a running session.Close the browser from your client.
4295 browsers already running (code brw01).Close one, or wait for an unused connect_url to expire (45 s).

Connection close codes ​

When a session can't start, or ends because of a limit, the WebSocket closes with one of these codes. Puppeteer and Playwright report it as a disconnect.

CodeMeaningCharged
1000Your client disconnected.Yes
4000The session's settings were refused.No
4001The proxy's exit IP couldn't be located, so the time zone and geolocation couldn't match it.No
4002The proxy didn't work: unreachable, wrong credentials, or no IP available.No
4003A limit was reached: session length, idle time or traffic. The reason says which.Yes
4004The browser closed: after browser.close() (reason browser closed), or because it failed.Yes, for the traffic it used
4005No browser free on our side.No

For 4001, 4002 and 4005, create a new browser and try again.

GET /v1/browsers/{id} gives the code and reason of a session that ended (end_code, end_reason).