Error Handling

An error comes either from us (the proxy) or from the site you requested. You can always tell which:

Every error from the proxy has an X-Proxy-Error header with a code like PX1002. If the header is missing, the response came from the site and we passed it on unchanged.

The first line of the body repeats the code, so you can read it without checking headers:

Response

HTTP/1.1 502 Bad Gateway
X-Proxy-Error: PX1002
Content-Type: text/plain; charset=utf-8

PX1002: no exit node available for the requested targeting

Most clients hide this on https:// URLs. An HTTPS request opens a tunnel with CONNECT. When that fails, libraries such as Python requests, Node axios and Go’s http.Client raise a connection error instead of returning the response, so you only see the status, for example Tunnel connection failed: 502 Bad Gateway.curl -v still shows the code, and the table below lists which codes each status can mean. On http:// URLs you can always read the header.

When you can read the code, check the code rather than the HTTP status. Sites use the same statuses, but the codes are ours and won’t change.

Errors You Can Fix

The request needs to change. Sending it again unchanged gives the same error.

Code	Status	Meaning	Fix
`PX1004`	`400`	Unsupported targeting option in the username.	Check the spelling of your `country`, `state`, `city`, `isp` or `os` value. Use lowercase values with no spaces, like `city-losangeles`. Remove options one at a time to find the wrong one. See Basics.
`PX2001`	`407`	Invalid proxy credentials.	Check your credentials in the dashboard. The username must start with `client-CLIENT_ID`, and your client must send `Proxy-Authorization`, not `Authorization`.
`PX2002`	`407`	No data left.	Your plan’s data is used up, so no new sessions can start. Top up or upgrade and the proxy works again right away.
`PX2005`	`503`	Data ran out during the request.	Same as `PX2002`, but it happened partway through. Any response you got is incomplete.
`PX2003`	`403`	Destination port not allowed.	Mail (SMTP, POP3, IMAP), FTP, SSH and Telnet ports are blocked. Ports `80` and `443` always work.
`PX2004`	`400`	Malformed request.	Plain HTTP needs a full URL in the request line, and HTTPS needs `CONNECT host:port`. Check your client’s proxy settings.

A 407 only ever means a problem with your credentials or your data balance. Sending the password again won’t help if the code is PX2002.

Errors Worth Retrying

These come from the exit network. The same request often works a moment later.

Code	Status	Meaning	What to do
`PX1002`	`502`	No exit node matches your targeting right now.	Narrow targeting has fewer IPs and can run out at busy times. Add `fallback-true` to accept another location in the same country, try again shortly, or remove the most specific parameter, city first and then state.
`PX1005`	`504`	Timed out while connecting.	Try again. Broader targeting connects faster because there are more IPs to choose from.
`PX1006`	`503`	Exit network unavailable.	A problem on our side. Try again shortly, and contact support if it lasts more than a few minutes.
`PX1000`	`502`	Upstream network error.	Try again with backoff. If it keeps happening, send us the code, the time and the target host.
`PX1001`	`502`	The exit network rejected the session.	Usually short-lived and on our side. Try again in a moment.

Retry with exponential backoff and use a new session-SESSION_ID for each attempt. Retrying the same session with the same narrow targeting tends to hit PX1002 again.

Errors About the Destination

Code	Status	Meaning	What to do
`PX1003`	`403`	The exit network doesn’t allow this host, port or protocol.	Check the address and port. Contact support if you think it should work.
`PX1007`	`502`	The destination refused the connection.	The site isn’t listening on that port, or it blocks that IP. Check the host and port, then try again. Another IP may get through.
`PX1008`	`502`	The sticky session has run out.	Change the session ID in your username to start a new session. Your data balance is not affected.

Errors From the Site

If a response has no X-Proxy-Error header, it came from the site you requested, exactly as they sent it. We never change a site’s status, headers or body.

Status	Meaning	Fix
`403 Forbidden`	The site is blocking the request.	Use a new session to get a new IP, and try a different country or region.
`429 Too Many Requests`	The site is rate-limiting you.	Slow down and switch IPs more often.
`404`, `5xx`	The site’s own error.	Handle it as you would without a proxy. Retry `5xx` with backoff.

This is why the PX code matters: a 403 from us (PX1003) and a 403 from the site need completely different fixes.

Handling Errors in Code

On http:// URLs, read the header:

Python

import requests

proxy = "http://client-CLIENT_ID-country-us-session-abc123:PASSWORD@residential.roundproxies.com:5000"
r = requests.get("http://example.com", proxies={"http": proxy})

code = r.headers.get("X-Proxy-Error")
if code is None:
    pass                        # the site answered, r is its response
elif code in ("PX1000", "PX1001", "PX1002", "PX1005", "PX1006"):
    pass                        # temporary: retry with backoff and a new session
elif code in ("PX2002", "PX2005"):
    pass                        # out of data: stop and top up
else:
    pass                        # the request needs fixing, don't retry

On https:// URLs, catch the proxy error and check the status in its message:

Python

import requests

proxy = "http://client-CLIENT_ID-country-us-session-abc123:PASSWORD@residential.roundproxies.com:5000"
try:
    r = requests.get("https://example.com", proxies={"https": proxy})
except requests.exceptions.ProxyError as e:
    text = str(e)               # "... Tunnel connection failed: 502 Bad Gateway"
    if "502" in text or "503" in text or "504" in text:
        pass                    # temporary: retry with backoff and a new session
    elif "407" in text:
        pass                    # your credentials, or you are out of data
    else:
        pass                    # 400 or 403: the request needs fixing

To see the exact code while debugging an HTTPS request, use curl -v and look at the CONNECT response:

cURL

curl -v -x "http://client-CLIENT_ID-country-us:PASSWORD@residential.roundproxies.com:5000" \
     https://example.com
# < HTTP/1.1 502 Bad Gateway
# < X-Proxy-Error: PX1002

Reading the Code on HTTPS

If you only have the status, this is what it can mean:

Status	Possible codes	Retry?
`400`	`PX1004`, `PX2004`	No. Fix the username or the request.
`403`	`PX1003`, `PX2003`	No. The destination or port is not allowed.
`407`	`PX2001`, `PX2002`	No. Check your credentials, then your data balance.
`502`	`PX1000`, `PX1001`, `PX1002`, `PX1007`, `PX1008`	Yes, with backoff and a new session ID.
`503`	`PX1006`, `PX2005`	Yes, unless you are out of data.
`504`	`PX1005`	Yes, and consider broader targeting.

Connection Problems

Some failures happen before there is any HTTP response, so they have no code:

Problem	Cause	Fix
`Connection refused` or `reset` when reaching the proxy	You couldn’t reach us at all.	Check your outbound firewall and use port `5000` for HTTP or `5001`/`5002` for SOCKS5.
UDP relay is set up but no UDP replies arrive	UDP is blocked, or sent from a different IP than your SOCKS5 login.	See UDP over SOCKS5.
Response cut off partway	Your data ran out while downloading, or the session closed.	Check your balance. A cut-off response with no error usually means you hit your limit mid-download.

Still Stuck?

Email team@roundproxies.com or visit the Help Center. Include the PX code and the time of the request so we can find the problem quickly.

Getting Started

Residential Proxies

ISP Proxies

Datacenter Proxies

Reseller

Errors You Can Fix

Errors Worth Retrying

Errors About the Destination

Errors From the Site

Handling Errors in Code

Reading the Code on HTTPS

Connection Problems

Still Stuck?

​Errors You Can Fix

​Errors Worth Retrying

​Errors About the Destination

​Errors From the Site

​Handling Errors in Code

​Reading the Code on HTTPS

​Connection Problems

​Still Stuck?

Errors You Can Fix

Errors Worth Retrying

Errors About the Destination

Errors From the Site

Handling Errors in Code

Reading the Code on HTTPS

Connection Problems

Still Stuck?