Error Handling

When something goes wrong, the error either comes from us (the proxy) or from the target site you asked for. Telling them apart used to require guesswork. Now it doesn’t:

Every error generated by the proxy carries an X-Proxy-Error response header with a stable code like PX1002. If that header is absent, the response came from the target site and we passed it through untouched.

The response body repeats the code on its first line, so you can read it without inspecting headers:

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

On https:// URLs, most clients hide this. An HTTPS request opens a tunnel with CONNECT, and when that fails, libraries like Python requests, Node axios and Go’s http.Client raise a connection error instead of returning a response — so the header and body never reach your code. You get the status only: Tunnel connection failed: 502 Bad Gateway.The code is still on the wire. curl -v shows it, and the table below maps each status back to its possible causes. On http:// URLs the header is always readable.

Where you can read the code, match on it rather than on the HTTP status: statuses are shared with the target site, while the codes are ours alone and will not change.

Errors you can fix

These mean the request needs to change. Retrying it unchanged returns the same error.

Code	Status	Meaning	Fix
`PX1004`	`400`	Unsupported targeting option in username.	Check the spelling of your `country`, `state`, `city` or `isp` segment. Use lowercase, dash-separated values (`city-berlin`). Remove options one at a time to find the bad one — see Basics.
`PX2001`	`407`	Invalid proxy credentials.	Verify your credentials in the dashboard. The username must start with `client-CLIENT_ID`, and your client must send `Proxy-Authorization`, not `Authorization`.
`PX2002`	`407`	Bandwidth limit exceeded.	Your plan’s data is used up and no new sessions can start. Top up or upgrade — the proxy resumes automatically.
`PX2005`	`503`	Bandwidth limit reached mid-request.	Same as `PX2002`, but you ran out partway through. Any response you received 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 target.	Plain HTTP needs an absolute URL in the request line; HTTPS needs `CONNECT host:port`. Check your client’s proxy settings.

A 407 now only ever means your credentials or your data balance. It is never a problem on our side, so re-sending the password will not help when the cause is PX2002.

Errors worth retrying

These are conditions in the exit network. The same request will often succeed a moment later.

Code	Status	Meaning	What to do
`PX1002`	`502`	No exit node matches your targeting right now.	Narrow targeting has fewer nodes and runs dry at busy times. Retry shortly, or drop the most specific parameter — city first, then state.
`PX1005`	`504`	Timed out establishing the connection.	Retry. Wider targeting connects faster, because there are more nodes to choose from.
`PX1006`	`503`	Exit network unavailable.	A problem on our side, not with your request. Retry shortly; contact support if it lasts more than a few minutes.
`PX1000`	`502`	Upstream network error.	Retry with backoff. If it persists, send us the code, the time, and the target host.
`PX1001`	`502`	Exit network rejected the session.	Usually temporary and on our side. Retry in a moment.

Use exponential backoff and rotate to a new session-SESSION_ID between attempts. Hammering the same session and the same narrow targeting tends to hit PX1002 repeatedly.

Errors about the destination

Code	Status	Meaning	What to do
`PX1003`	`403`	The exit network does not permit this destination host, port or protocol.	Check the address and port. Contact support if you believe it should be reachable.
`PX1007`	`502`	The destination refused the connection.	The target is not listening on that port, or it is blocking that exit IP. Verify host and port, then retry — a different exit node may be accepted.
`PX1008`	`502`	Sticky session exhausted.	Change the session ID in your username to start a fresh session. Your account’s data balance is unaffected.

Errors from the target site

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

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

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

Handling errors in code

On http:// URLs, read the header directly:

import requests

proxy = "http://client-CLIENT_ID-country-de-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 target site answered; r is their response
elif code in ("PX1000", "PX1001", "PX1002", "PX1005", "PX1006"):
    pass                        # transient — retry with backoff, new session
elif code in ("PX2002", "PX2005"):
    pass                        # out of data — stop and top up
else:
    pass                        # your request needs fixing — do not retry

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

import requests

proxy = "http://client-CLIENT_ID-country-de-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                    # transient — retry with backoff, new session
    elif "407" in text:
        pass                    # your credentials, or you are out of data
    else:
        pass                    # 400 or 403 — your request needs fixing

To see the exact code while debugging an HTTPS failure, use curl -v and read the CONNECT response:

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

Reading the code on HTTPS

When you only have the status, this is what it narrows down to:

Status	Possible codes	Safe to 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 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-level failures

Some failures happen before any HTTP response exists, so they carry no code:

Symptom	Meaning	Fix
`Connection refused` / `reset` reaching the proxy	You could not reach us at all.	Check outbound firewall rules and confirm you are using port `5000`.
Response body cut off mid-transfer	Your data ran out while streaming, or the session was closed.	Check your balance — a truncated body with no error is the signature of hitting your limit mid-download.

Still stuck?

Reach out at team@roundproxies.com or visit the Help Center. Quote the PX code and the time of the request — it tells us exactly which stage failed.

Getting Started

Residential Proxies

ISP Proxies

Datacenter Proxies

Reseller

Reseller API

Errors you can fix

Errors worth retrying

Errors about the destination

Errors from the target site

Handling errors in code

Reading the code on HTTPS

Connection-level failures

Still stuck?

​Errors you can fix

​Errors worth retrying

​Errors about the destination

​Errors from the target site

​Handling errors in code

​Reading the code on HTTPS

​Connection-level failures

​Still stuck?

Errors you can fix

Errors worth retrying

Errors about the destination

Errors from the target site

Handling errors in code

Reading the code on HTTPS

Connection-level failures

Still stuck?