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.

Where the failure came from

Read the response first. Most failures fall into one of these:

What you see	What failed	Go to
`401`, `403`, `404`, `422`	Your request or account: token, host, plan, or body	Request errors
`429`, `parallel_browsers_limit_reached`	An account limit	Limits
`proxy_required`, `bad_proxy`, `tunnel_not_ready`, `proxy_provider_error`	The browser’s connection to the internet	Proxy errors
`browser_failed_to_start`, `profile_start_failed`, `invalid_fingerprint`	Browser startup	Errors from the browser
`Target closed`, `Profile not found`, a dropped CDP socket	The session ended while the job was still running	The browser stopped by itself
`cluster_is_full`, `service_unavailable`, `app_outdated`, `502`, `503`	Surfsky infrastructure. Retry it	Retrying
`success: true`, but the result is wrong	The target site	The site is blocking you

A browser can start, /scrape can return HTTP 200, and the page can still hold a challenge or an empty result, so check the content and not only the status.

Which timeout fired

Symptom	Timeout	What to change
`400 scrape_timeout`	The 120-second budget for one `/scrape` call	Narrow `wait_for`, or split the batch
`Target closed` part way through a job	`inactive_kill_timeout`, 30 seconds by default	Raise it for long waits and manual work
Your framework times out while the browser is still running	The framework’s own navigation or selector timeout	Wait for a selector that proves the content is ready

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

These errors return HTTP 429. Profile API responses include headers for the current request limits and remaining allowance; 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 errors come from the container running your browser. They usually appear during startup, scraping, or cookie requests.

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

Where the failure came from

Which timeout fired

Retrying

Request errors

Limit errors

Errors from the browser

Validation errors

​Where the failure came from

​Which timeout fired

​Retrying

​Request errors

​Limit errors

​Errors from the browser

​Validation errors

Where the failure came from

Which timeout fired

Retrying

Request errors

Limit errors

Errors from the browser

Validation errors