Errors

Most API errors use this shape:

{
  "success": false,
  "msg": "Maximum parallel browsers",
  "data": null,
  "code": "parallel_browsers_limit_reached"
}

Use the HTTP status and code, when present, to choose an action. Keep msg for logs and diagnostics. data may contain validation details or information from the browser. Some forwarded browser responses and scraping errors do not include code, and may use detail or error instead. Your error handler should tolerate these shapes and non-JSON responses from a network intermediary. Record the status and x-cloud-tracing-uuid header when available.

Retrying

Choose retries by the reported condition rather than the HTTP status alone:

Condition	Action
`cluster_is_full`, temporary startup or provider failure, `503`	Retry with bounded exponential backoff and jitter. Stop after a limited number of attempts.
`rate_limits_reached`	Wait and reduce the request rate. Either the minute or hour window may be exhausted.
`parallel_browsers_limit_reached`	Wait for a slot or stop a session your job owns.
Traffic quota exhausted	Check the allowance and reset time; repeated immediate retries will not help.
Invalid credentials, missing resource, invalid body, unavailable account feature	Correct the request or account configuration first.
`profile_is_running`	Stop the profile before editing, deleting, or importing cookies.
`profile_version_conflict`	Re-read the profile, reconcile the intended change, then retry.

A 400 cluster_is_full can be retried; a 429 caused by exhausted traffic quota needs a different response. HTTP status alone cannot distinguish these cases. If a start request times out or loses its connection, its outcome is uncertain. Check active sessions before repeating it. Creating a profile or one-time session is not an idempotent operation, so an automatic retry can create an extra resource.

Request errors

Status	Code	What it means
400	`proxy_required`	The browser has no way out to the internet. Pass `proxy`, `open_vpn`, or `wireguard`, or use a plan with a pool.
400	`cluster_is_full`	No capacity right now. Retry with backoff.
400	`profile_start_failed`	The browser did not come up. Retry with backoff; if it repeats, inspect the response details and the proxy configuration.
400	`profiles_limit_reached`	Your plan’s persistent profile limit. Delete unused profiles.
400	`persistent_profiles_not_allowed`	Your plan is one-time only.
400	`proxy_pool_unavailable`	No pool is attached to your account. Bring your own proxy.
400	`shared_pool_country_unavailable`	The shared pool has nothing in that country at the moment. Pick another, or use premium.
400	`proxy_provider_error`	The upstream proxy provider failed. Retry.
400	`chromedriver_not_enabled`	Start the profile with `enable_chromedriver: true` before talking to the ChromeDriver endpoint.
400	`scrape_timeout`	`/scrape` gave up after 120 seconds. Usually the page never satisfied your wait condition.
400	`extension_limit_reached`	100 extensions per account.
400	`no_file_provided`	The extension upload had no file part.
400	`user_is_blocked`	The account is blocked. Contact support.
401	`not_authorized`	Missing or wrong `X-Cloud-Api-Token`.
403	`subscription_is_expired`	No active subscription.
403	`namespace_not_allowed`	Your account is served by a dedicated host and you called the shared one. Use the host you were given.
403	`premium_pool_unavailable`	Premium proxies are not enabled for your account.
403	`shared_pool_unavailable`	Shared proxies are not enabled for your account.
403	`region_not_chosen`	Pick a region in the dashboard before starting browsers.
403	`region_managed`	Your plan’s region is assigned by support, not self-serve.
404	`profile_not_found`	No such profile, or it belongs to another account. The API does not distinguish the two.
404	`extension_not_found`	No such extension.
404	`plan_not_exists`	No such plan.
404	`premium_quota_not_applicable`	This plan bills premium traffic per GB and has no quota to report.
409	`profile_is_running`	You tried to edit or delete a profile that is up. Stop it first.
409	`browsers_still_running`	The operation needs every browser stopped.
500	`extension_upload_failed`	Upload to storage failed. Retry.
500	`extension_delete_failed`	Delete from storage failed. Retry.
500	`proxy_locations_unavailable`	The proxy provider’s location list could not be fetched.
502	`unexpected_browser_response`	The browser answered with something that was not JSON. Check whether the session is still active, then inspect or stop it before replacing it.
503	`service_unavailable`	Temporary. Retry with backoff.

Limit errors

All of these are 429. Responses to profile calls carry your current window in headers - see Limits.

Code	What it means
`rate_limits_reached`	Requests per minute or per hour exceeded. Wait for the window.
`parallel_browsers_limit_reached`	You already have as many browsers running as your plan allows. Stop one, or check `GET /users/browser-limits` before starting.
`shared_traffic_limit_reached`	Shared proxy traffic allowance exhausted. Switch to your own proxy or to premium.
`premium_traffic_limit_reached`	Premium proxy quota exhausted. Top up or use your own proxy.
`region_change_too_soon`	Regions cannot be changed again this soon.

Errors from the browser

These come from the pod running your browser rather than the API gateway, so you will usually see them on start, on /scrape, or on a cookie call.

Status	Code	What it means
400	`bad_proxy`	The proxy did not accept the connection, or failed to route. Check credentials and that the endpoint is reachable.
400	`invalid_fingerprint`	The browser rejected the fingerprint. Check its fields against the fingerprint reference.
400	`cookies_not_found`	The profile has no stored cookies to export.
400	`cookies_disabled`	The profile’s storage options have cookies turned off.
400	`pod_is_acquired`	The session is already in use.
409	`profile_version_conflict`	The profile changed between the read and the write. Re-read it and retry.
422	`validation_error`	Malformed request body. `data` lists the fields.
500	`browser_failed_to_start`	The browser process died during startup. `data` carries what it printed.
503	`app_outdated`	The browser image is being updated. Retry shortly.
503	`tunnel_not_ready`	The proxy tunnel did not come up in time. Retry.

Validation errors

Gateway validation errors return 422 validation_error with the failing fields in data. For example:

{
  "success": false,
  "msg": "Validation error",
  "code": "validation_error",
  "data": [
    {
      "loc": ["body", "fingerprint", "os"],
      "msg": "Input should be 'win', 'mac' or 'android'",
      "type": "enum"
    }
  ]
}

Using the API

Profiles

Proxies

Fingerprints

Extensions

CAPTCHA

Retrying

Request errors

Limit errors

Errors from the browser

Validation errors

​Retrying

​Request errors

​Limit errors

​Errors from the browser

​Validation errors

Retrying

Request errors

Limit errors

Errors from the browser

Validation errors