Proxy support

Every browser runs behind a proxy. There is no launch without one: a create with no proxy returns 400 with PROXY_REQUIRED.

All of the session’s traffic goes through it. At launch the browser looks up its own exit IP through the proxy and sets its timezone, locale and geolocation from it, and WebRTC reports that exit IP rather than the address of the machine the browser runs on.

The form

scheme://username:password@host:port

Rule	Detail
Scheme	`http`, `https`, `socks5` or `socks5h`. Case is ignored
Host	Required
Port	Required, written out, 1 to 65535
Credentials	Optional. An IP-authenticated proxy has none
Whitespace	Rejected anywhere in the string

Two forms that look fine and are not:

user:[email protected]:8000 has no scheme. URL parsers read user as the scheme, so it fails with PROXY_INVALID and the detail scheme user is not supported.
http://user:[email protected] has no port. PROXY_INVALID, with the detail missing port.

Writing the default port out is fine. http://host.example.com:80 is valid.

Encode the password

@, :, /, #, %, & and space all have to be percent-encoded in the username and the password. encodeURIComponent in JavaScript, urllib.parse.quote(value, safe='') in Python.

A raw / or # ends the authority and the whole string fails to parse. A raw space is rejected outright, because URL parsers quietly repair it to %20 and would otherwise accept a proxy you did not mean to send.

from urllib.parse import quote

proxy = f"http://{quote(login, safe='')}:{quote(password, safe='')}@us-east.gw.rayobyte.com:8000"

Input	Result	Detail
`http://login:p%[email protected]:8000`	Valid, password is `p@ss`	—
`http://login:p/[email protected]:8000`	`PROXY_INVALID`, the `/` was not encoded	`could not be parsed as a URL`
`http://login:p#[email protected]:8000`	`PROXY_INVALID`, the `#` was not encoded	`could not be parsed as a URL`
`http://login:p [email protected]:8000`	`PROXY_INVALID`, raw space	`proxy must not contain spaces`
`ftp://user:[email protected]:21`	`PROXY_INVALID`, scheme not accepted	`scheme ftp is not supported`
`http://user:[email protected]:99999`	`PROXY_INVALID`, port out of range	`port out of range`
`""` or `" "`	`PROXY_REQUIRED`	`no proxy supplied`

On GET /connect the code is in the X-Error-Code response header and the detail is in parentheses at the end of the plain-text body. On POST /api/browser/create both are fields of the JSON body.

Rayobyte residential proxies

In the Rayobyte dashboard the proxy field on the Browser launch page arrives pre-filled with your own residential credentials and a fresh sticky session id appended to the password:

http://cust12345:[email protected]:8000

The -session- suffix is 8 lowercase letters and digits and it pins the browser to one exit IP for the life of the session. Without it every request inside the browser can leave from a different IP, which breaks any site that ties a login or a cart to an address. That is why the dashboard adds one and why it is not optional there.

Append the suffix to the password as it is. Percent-encoding leaves -, letters and digits unchanged, so encoding before or after makes no difference.

Read Sticky sessions for how session ids behave on the proxy side, including what happens when the device you are pinned to drops off.

You can replace the pre-filled value with any proxy that meets the rules above.

Sending it

curl -G "https://browser.rayobyte.com/connect" \
  --data-urlencode "os=windows" \
  --data-urlencode "proxy=http://USERNAME:[email protected]:8000" \
  -H "x-api-key: rb_live_YOUR_KEY"

ws_url = client.connect_url(
    os="windows",
    proxy="http://USERNAME:[email protected]:8000",
)

const wsUrl = await client.connectUrl({
  os: 'windows',
  proxy: 'http://USERNAME:[email protected]:8000',
});

The proxy’s form is checked before a browser is started, so a malformed string costs you nothing against your 48 browser hours.

The proxy itself is not dialed until the browser starts. A well-formed proxy with the wrong password, or one that is down, fails at launch with 422 and the code PROXY_UNREACHABLE: a JSON { error, code } body on POST /api/browser/create, and a plain-text body with an X-Error-Code header on GET /connect. The message is the same on both:

The browser could not connect through that proxy. Check the proxy host, port, username and password.

Retrying with the same proxy returns the same thing, so test the proxy on its own:

curl -x "http://USERNAME:[email protected]:8000" https://api.ipify.org

Was this page helpful?