> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfsky.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Read API error responses, choose a retry policy, and diagnose request or browser failures.

Most API errors use this shape:

```json theme={null}
{
  "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`, `402`, `403`, `404`, `422` | Your request or account: token, balance, host, plan, or body | [Request errors](#request-errors) |
| `429`, `parallel_browsers_limit_reached` | An account limit | [Limits](https://docs.surfsky.io/limits.md) |
| `proxy_required`, `bad_proxy`, `tunnel_not_ready`, `proxy_provider_error` | The browser's connection to the internet | [Proxy errors](https://docs.surfsky.io/proxies.md#proxy-errors) |
| `browser_failed_to_start`, `profile_start_failed`, `profile_needs_newer_browser` | Browser startup | [Errors from the browser](#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](https://docs.surfsky.io/troubleshooting.md#the-browser-stopped-by-itself) |
| `cluster_is_full`, `service_unavailable`, `app_outdated`, `502`, `503` | Surfsky infrastructure. Retry it | [Retrying](#retrying) |
| `success: true`, but the result is wrong | The target site | [The site is blocking you](https://docs.surfsky.io/troubleshooting.md#the-site-is-blocking-you) |

A browser can start, `/scrape` can return HTTP 200, and the page can still be a challenge page or empty, so read `challenge` and the content, 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 shorten the waits |
| `400 page_load_timeout`, `400 selector_timeout` | `timeout` of the scrape body, 30 seconds by default | Wait for a selector that proves the content is ready, or raise `timeout` |
| `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](https://docs.surfsky.io/sessions.md#find-running-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` | A scrape call gave up after 120 seconds. Usually the page never satisfied your wait condition. |
| 400 | `page_load_timeout`, `selector_timeout`, `site_unreachable`, `action_failed` | A scrape did not finish; `data` carries the page the browser was left on, `challenge` and `receipt`. A response with the page is charged, one without is free. See [Scraping API](https://docs.surfsky.io/quickstart/scraping_api.md#read-the-response). |
| 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`. |
| 402 | `insufficient_balance` | The balance is empty. Top up in the dashboard; [GET /billing/balance](https://docs.surfsky.io/api-reference/billing/get-balance.md) shows what is left. |
| 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. |
| 404 | `billing_session_not_found` | No receipt for that session on your account. |
| 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](https://docs.surfsky.io/limits.md).

| 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. |
| `site_report_limit_reached` | More than 1 site report per minute or 20 per day. Wait before sending the next one. |
| `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 | `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. |
| 409 | `profile_needs_newer_browser` | The profile was last saved by a newer browser version than the one running now. It opens once the cloud browser is updated to that version. |
| 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:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.