Error & Response Code Reference
What every error means and how to fix it, covering Error 407 Proxy Authentication Required, 502/503/504 gateway failures, connection timeouts, plus target-site 403, 429 and CAPTCHA responses.
The first question with any proxy error is which side it came from. Errors from the Proxio gateway are about your connection to Proxio. Everything else you see (403, 429, CAPTCHAs) is the destination site's response, delivered back to you through the tunnel. Use the two tables below to tell them apart and act.
Errors from the Proxio gateway
These are the codes the gateway itself emits (over HTTP; for SOCKS5 see the note
below the table). Gateway error responses carry a Proxy-Agent: proxio-pop
header, which is a quick way to confirm the answer came from Proxio and not the
target.
| Code | What it means | How to fix |
|---|---|---|
| 407 Proxy Authentication Required | The gateway rejected or never received your credentials: wrong username/password, an unparseable username, or a passwordless connection from an IP that has no IP-auth binding. | Re-copy your username and password (no whitespace). Using IP-allowlist auth? Confirm your current public IP is still whitelisted on that credential. Confirm the credential was not deleted or rotated. See Connection & Authentication. |
| 402 Quota Exceeded / Package Expired | Your package's data quota is used up, or the package itself has expired. | Check remaining quota in Usage Statistics, then top up and buy more GB, renew the package, or raise the credential's own quota cap if you set one. |
| 403 Source IP Not Allowed | The credential has a source-IP allowlist and your current IP is not on it. | Add your IP to the credential's allowed list, or connect from an allowed IP. Note your public IP may have changed since you set the list. |
| 403 Destination Not Allowed / Forbidden | The destination is blocked: by a blocklist rule on your own credential (these responses carry an X-Proxio-Blocked: customer-rule header), or by platform-level restrictions. | If it is your own rule, edit the credential's Blocked destinations tab. Otherwise the target is restricted; see Acceptable Use. |
| 429 Too Many Connections | You hit the per-credential concurrency cap (2,000 parallel connections). | Lower your client's concurrency, or spread the job across multiple credentials: each one gets its own 2,000-connection budget. |
| 502 Upstream Connect Failed / Upstream Unavailable | The gateway could not establish the outbound connection for this request. | Connection-level failure. On smart rotation these retry automatically; otherwise just resend, since a different exit usually succeeds. See the note below. |
| 503 Auth Backend Unreachable | The gateway could not verify credentials against the platform right now. | Temporary. Wait a few seconds and retry; if it persists for minutes, open a ticket. |
Connection refused / timed out to geo.proxio.cc:16666 | Your client never reached the gateway. | Your network or firewall is blocking outbound port 16666 (common on corporate and campus networks). Retest on another network with the verbose self-test on the Start Here page. If it fails everywhere, open a ticket. Also note the gateway drops clients that take longer than 10 seconds to complete the proxy handshake. |
Two quirks worth knowing
The gateway's 407 does not include a Proxy-Authenticate challenge header, so
always send credentials proactively in the proxy URL instead of waiting to be
challenged (every example in these docs already does this). And over SOCKS5,
most of the failures above collapse into a single generic reply (connection
refused, code 0x05): if you need to tell quota from auth from blocking apart,
test the same request over HTTP first.
What smart retry does
On smart rotation, Proxio automatically retries connection-level failures (TCP dial errors, CONNECT timeouts, and 502/503/504) up to 5 attempts, taking a fresh IP on each attempt when retryrotate is on (the default). Retried attempts transfer no data and never count against your quota. Content errors like 403 are never retried. On auto or sticky rotation without retry, just resend the request yourself.
Errors from the target website (NOT the proxy)
Proxio is an L4 passthrough that never terminates or inspects your TLS traffic. Any status code that comes back through the tunnel is the destination's response. Treat these as the site's anti-bot behavior and rotate.
| Code | What it means | How to fix |
|---|---|---|
| 403 Forbidden | The destination refused this exit IP: an IP-level ban or geo-block. Not a Proxio error, and not retried by smart retry. | Rotate to a fresh IP: start a new sessid, or switch the credential to auto mode for a new IP per request. Narrow your geo to the region the site expects. |
| 429 Too Many Requests | The target is rate-limiting you. | Slow down and add backoff. Spread requests across several sticky sessions or IPs instead of hammering one. |
| CAPTCHA / challenge page | The site is challenging the request (bot detection), often returned with a 200 or a 403. | Rotate the IP, narrow your geo targeting, and send browser-like headers such as User-Agent and Accept-Language. Consider SOCKS5 (socks5h://). |
If the status code arrived through the tunnel from the destination, it is the site's response, not Proxio's. A 5xx from the target's own CDN is a target-side error. Approach it the same way as the rows above: rotate and retry against the site, not against the gateway.
Related pages
Troubleshooting: Start Here
A symptom index for Proxio. Find your problem, run the numbered checks, and jump straight to the fix for connection failures, 407s, wrong locations, slow speeds, blocks, and billing.
Connection & Authentication Problems
Fix Proxio connection failures and Error 407 by verifying the endpoint, copying credentials whole, URL-encoding passwords, picking the right scheme, and diagnosing IP-allowlist auth issues.