> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/agent-browser/response-codes.md).

# Response Codes

Find out what Agent Browser errors mean and how to resolve them.

Errors appear at different stages, so start by finding where yours occurs:

<table><thead><tr><th width="122.5">Stage</th><th>How the error appears</th></tr></thead><tbody><tr><td><a href="#connection-errors">Connection</a></td><td>An HTTP status and message when the connection is rejected.</td></tr><tr><td><a href="#session-errors">Session</a></td><td>The WebSocket closes with code <code>3000</code> and a <code>CDP_*</code> reason.</td></tr><tr><td><a href="#in-page-errors">In page</a></td><td>A CDP command returns error code <code>1337</code>.</td></tr><tr><td><a href="#network-errors">Page traffic</a></td><td>A response includes the <code>X-Error-Description</code> header.</td></tr></tbody></table>

### Connection errors

The connection is rejected before the browser session starts.

#### Authentication and parameters

<table><thead><tr><th width="78">Code</th><th>Message</th><th>Cause and solution</th></tr></thead><tbody><tr><td><code>400</code></td><td><code>invalid_uri, &#x3C;details></code></td><td>The connection URL or a query parameter is malformed. Check the URL syntax.</td></tr><tr><td><code>400</code></td><td><code>invalid source: &#x3C;src></code></td><td>Unsupported <code>p_src</code> value. Use <code>oxybrowser</code> or remove the parameter.</td></tr><tr><td><code>400</code></td><td><code>session_name must be 3-36 alphanumeric or '-'</code></td><td>Invalid <code>session_name</code>. Use the pattern <code>^[A-Za-z0-9-]{3,36}$</code>.</td></tr><tr><td><code>400</code></td><td><code>keep_alive requires session_name</code></td><td><code>keep_alive=true</code> was set without <code>session_name</code>.</td></tr><tr><td><code>400</code></td><td><code>o_profile_save requires o_profile</code></td><td><code>o_profile_save</code> was set without a profile name.</td></tr><tr><td><code>400</code></td><td><code>o_profile must contain only letters, numbers...</code></td><td>Invalid profile name. Use the pattern <code>^[a-zA-Z0-9][a-zA-Z0-9_-]{2,35}$</code>.</td></tr><tr><td><code>400</code></td><td><code>record_name requires record=true</code></td><td>Add <code>record=true</code> to the connection URL.</td></tr><tr><td><code>400</code></td><td><code>page handler is not enabled for this account</code></td><td>Remove <code>page_handler</code> or contact Oxylabs support.</td></tr><tr><td><code>401</code></td><td><code>missing auth header</code></td><td>No credentials received. Pass them in the URL: <code>wss://USER:PASS@...</code>.</td></tr><tr><td><code>401</code></td><td><code>invalid auth header / not a valid base64</code></td><td>Malformed credentials. Pass them in the URL instead of building custom headers.</td></tr><tr><td><code>401</code></td><td><code>missing credentials</code></td><td>Credentials are not in the <code>username:password</code> format.</td></tr><tr><td><code>401</code></td><td><code>invalid credentials</code></td><td>Wrong username or password, or the account is inactive. Check them in the dashboard.</td></tr><tr><td><code>403</code></td><td><code>source '&#x3C;source>' is not allowed</code></td><td>The <code>p_src</code> value is not enabled for your account. Contact support.</td></tr></tbody></table>

#### Features and limits

<table><thead><tr><th width="87">Code</th><th>Message</th><th>Cause and solution</th></tr></thead><tbody><tr><td><code>403</code></td><td><code>browser profile feature is not enabled</code></td><td>Persistent profiles are not enabled for your account. Contact support.</td></tr><tr><td><code>403</code></td><td><code>profile limit reached (&#x3C;N> maximum)</code></td><td>Delete unused profiles in the dashboard, or request a higher limit.</td></tr><tr><td><code>403</code></td><td><code>recordings are not enabled for this account</code></td><td>Contact support to enable session recording.</td></tr><tr><td><code>409</code></td><td><code>profile is already in use by another session</code></td><td>Another session is saving to this profile. Wait for it to finish, or connect without <code>o_profile_save</code>.</td></tr><tr><td><code>429</code></td><td><code>CDP_SESSION_RATE_LIMIT_REACHED</code></td><td>More than 10 new sessions started in one second. Space out connections and retry with backoff.</td></tr><tr><td><code>429</code></td><td><code>CDP_MAX_CONCURRENT_SESSIONS_REACHED</code></td><td>The concurrent session limit (100 by default) is reached. Close idle sessions and make sure <code>browser.close()</code> always runs.</td></tr><tr><td><code>429</code></td><td><code>CDP_MAX_PERSISTENT_SESSIONS_REACHED</code></td><td>The persistent session limit (5 by default) is reached. Reuse existing session names or wait for idle sessions to expire.</td></tr><tr><td><code>429</code></td><td><code>CDP_SESSION_IN_USE</code></td><td>The named session already has an active connection. Close it before reconnecting.</td></tr><tr><td><code>503</code></td><td><code>queue timeout</code></td><td>Capacity is temporarily saturated. Retry with exponential backoff.</td></tr></tbody></table>

### Session errors

The WebSocket connection closes with code `3000` and one of these reasons.

<table><thead><tr><th width="248.5">Reason</th><th>Cause and solution</th></tr></thead><tbody><tr><td><code>CDP_NO_BROWSERS_AVAILABLE</code></td><td>No browser is available right now. Retry with exponential backoff.</td></tr><tr><td><code>CDP_BROWSER_OVERWORKED_1</code></td><td>The browser host is saturated. Retry with backoff.</td></tr><tr><td><code>CDP_BROWSER_START_FAILED_0</code> <br><code>CDP_BROWSER_START_FAILED_1</code></td><td>The browser failed to start. Retry with backoff.</td></tr><tr><td><code>CDP_BROWSER_GONE</code></td><td>The browser stopped unexpectedly. Start a new session.</td></tr><tr><td><code>CDP_SESSION_NOT_FOUND</code></td><td>The named session expired after 10 minutes without a connection. Start a new session.</td></tr><tr><td><code>CDP_SESSION_IN_USE</code></td><td>Another client connected to the same named session. Use one connection per <code>session_name</code>.</td></tr><tr><td><code>CDP_BAD_PROXY</code></td><td>The proxy for the requested location could not be established. Retry, or use a new <code>proxy_resi_ses_id</code> for sticky sessions.</td></tr><tr><td><code>CDP_BAD_REQUEST</code></td><td>The proxy and location parameters are not a valid combination. Check them.</td></tr></tbody></table>

### In-page errors

These errors are returned as a CDP error with code `1337`.

<table><thead><tr><th width="311.5">Message</th><th>Cause and solution</th></tr></thead><tbody><tr><td><code>Invalid target</code></td><td><a href="/products/agent-browser/restricted-targets.md">Restricted targets</a>. Do not retry.</td></tr><tr><td><code>Too many targets</code></td><td>The session has more than <code>1000</code> open pages. Close pages when you are done with them.</td></tr><tr><td><code>Proxy not allowed in this context</code></td><td><code>Target.createBrowserContext</code> was called with <code>proxyServer</code>. Set proxy options in the connection URL instead.</td></tr></tbody></table>

### Network errors

When a page request fails, check the `X-Error-Description` header to see who returned the error:

```javascript
page.on("response", (res) => {
    const error = res.headers()["x-error-description"];
    if (error) console.warn(`Network error on ${res.url()}: ${error}`);
});
```

<table data-header-hidden><thead><tr><th width="154"></th><th></th></tr></thead><tbody><tr><td><strong>Header present</strong></td><td>The Oxylabs proxy network returned the error. Retry the request.</td></tr><tr><td><strong>Header missing</strong></td><td>The website itself returned the response, for example a <code>403</code> or a bot-protection page. Try a different location, device type or fingerprint.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/agent-browser/response-codes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.