Proxy Error Codes and the Fix for Each
The error codes the Proxies.sx gateway returns, with HTTP status, SOCKS5 reply, cause and fix, and how to tell a gateway refusal from a target error.
By Proxies.sx Team. Reviewed .
When the Proxies.sx gateway refuses a request, the response body starts with a code and ends with a request id, in the form CODE: message (req: id). A 407 code means credentials or balance, a 429 code means an account limit, a 502 code means no usable endpoint for your filters, and a 403 means the target address is blocked. Quote the req id when you contact support.
In this guide
Read the refusal before changing anything
The gateway answers a refused HTTP proxy request with a standard status line and a plain-text body. The body has three parts: a stable code such as E_NO_STOCK_COUNTRY, a sentence about the cause, and (req: <uuid>), a per-request id that lets support find the exact refusal in our logs. Scripts can branch on the code, and people can read the sentence.
The example below is a request we sent on 19 October 2026 without credentials. We used a plain http:// target on purpose. For an HTTPS target, the client first sends CONNECT, and curl prints only CONNECT tunnel failed, response 407 without the body that holds the code. The gateway runs the same credential and routing checks for both kinds of request, so repeating a failed HTTPS request against http://example.com/ shows you the code. If that plain request succeeds instead, the checks passed and the problem is specific to the HTTPS tunnel or the target.
$ curl -i -x http://gw.proxies.sx:7000 http://example.com/
HTTP/1.1 407 Proxy Authentication Required
connection: close
date: Mon, 19 Oct 2026 …
content-length: 90
server: Proxy
content-type: text/plain; charset=utf-8
proxy-authenticate: Basic realm="Proxy"
E_AUTH_REQUIRED: Proxy authentication required (req: 6f1c…)407 codes for credentials, balance and key caps
A 407 status asks the client to authenticate to the proxy (RFC 9110, section 15.5.8). Four different conditions on our gateway produce it, and each one needs a different fix.
| Code | What happened | What to do |
|---|---|---|
E_AUTH_REQUIRED | The request carried no Proxy-Authorization header. | Send the proxy username and password with the request. In browsers and automation tools, use the proxy authentication setting, covered in the tunnel failure guide. |
E_AUTH_INVALID | The username or password was rejected. The text after Invalid credentials carries the reason when one is available. | Use the proxy password from the dashboard or a valid pak_ key. Your dashboard login password is never accepted here. If the reason says Proxy password not set, generate one in the dashboard first. |
E_BALANCE_EXHAUSTED | The password was correct, but the account has no traffic left. | Add GB in the dashboard. Changing the password does not help. |
E_CAP_EXCEEDED | A pak_ access key reached the traffic cap its owner set. | Ask the key owner to raise the cap, or use another key. |
Accounts that are suspended or disabled also receive E_AUTH_INVALID. The code list in our gateway source defines an E_ACCOUNT_DISABLED value, but the gateway build checked on 19 October 2026 never returns it.
Two more responses come from the HTTP layer before any of these checks: a 400 with Invalid "Proxy-Authorization" header when the header is malformed, and a 400 saying the header must use the Basic type. Both mean the client built the header incorrectly. The authentication guide covers client-side credential problems in more detail.
429 codes for account limits
| Code | Limit | What to do |
|---|---|---|
E_RATE_LIMITED_AUTH | Too many failed logins from your IP address or for your account. | Stop the retry loop and fix the credentials before the next attempt. Each rejected login counts toward the limit. |
E_RATE_LIMITED_CONN | Too many open connections for the account. The default is 500 concurrent connections, and an administrator can set a different cap for an account. | Lower client concurrency or close idle keep-alive connections. |
E_SESSION_LIMIT | Too many active sessions. The message prints your count and the limit, for example (1000/1000). | Reuse session ids instead of creating a new one per request. An unused session expires after its TTL, as the sticky session guide explains. |
The limits in this table are the defaults configured on 19 October 2026. A website can also return 429 through an open tunnel, and that response is the website's decision, often with a Retry-After header (RFC 6585, section 4). The gateway's own 429 carries no Retry-After header, and it always has an E_ code in the body. For the website's kind, follow the Retry-After guide.
502, 503 and 59x when the route cannot be built
These codes mean the gateway accepted your credentials but could not finish building the route. The 502 guide explains how to tell them apart from a 502 sent by the website.
| Status and code | What happened | What to do |
|---|---|---|
502 E_NO_STOCK_COUNTRY | No endpoint passes your pool, country and filters right now. The message names the filters it applied and links the live stock endpoint. | Check the country in the stock endpoint, remove narrow filters such as carrier or city, or switch pool. The mobile pool covers six countries only, listed in the username guide. |
502 E_STOCK_DEGRADED | An endpoint was selected, then disappeared before the connection completed, or the client closed during setup. | Retry after a short pause on a new connection. A sticky session moves to another endpoint under its failover policy. |
590 to 599 E_UPSTREAM_REFUSED | On HTTPS requests to residential peers, the peer or relay refused the tunnel. The message carries the upstream reason, such as UPSTREAM502 or ECONNREFUSED. | Retry once on a new connection. If one session id keeps failing, start a new session id. |
| 590 to 599, no code | The same upstream failure on paths that report it without an E_ code. These statuses come from proxy-chain, the open-source library the gateway is built on. | Read the status: 593 is a failed DNS lookup for the target, 594 a refused connection, 595 a reset, 597 failed upstream credentials, 599 a generic upstream error. |
503 E_INTERNAL | An internal step failed, for example auth backend busy, retry or Relay routing unavailable. | Retry with backoff. Report it with the req id if it persists. |
| 503, no code | Gateway restarting; reconnect shortly. | Reconnect after a few seconds. |
| 504 | The upstream connection timed out. | Retry with a longer client timeout or a different session. |
The 590 to 599 range is not part of HTTP. The proxy-chain documentation defines it because a bare 502 cannot say which upstream step failed. Clients treat these numbers as server errors, so a generic retry policy sees them as 5xx.
# Is there stock for the country you asked for? Counts only, per pool.
curl -s https://api.proxies.sx/v1/gateway/pool/stock \
| jq '{peer: .pools.peer.de, mobile: .pools.mbl.de, generatedAt}'403 and 400 codes for blocked targets, usernames and ports
| Status and code | What happened | What to do |
|---|---|---|
403 E_SSRF_BLOCKED | The target is a private, loopback or cloud metadata address. The gateway refuses these so the network cannot be used to reach internal systems. | Use a public hostname. If a public name resolves to a private address, the refusal stands. |
400 E_USERNAME_PARSE | The username was missing or longer than 256 characters. | Shorten the username. These are the only username mistakes that fail. The gateway repairs or skips the others silently, as the username guide explains. |
400 E_WRONG_PORT | The client spoke HTTP to the SOCKS5 port, or SOCKS to the HTTP port. | Use http:// with port 7000 or socks5h:// with port 7001. |
| 400, Invalid request | The request could not be parsed as HTTP. | Check that the client is configured for an HTTP proxy on port 7000. |
The E_WRONG_PORT response also carries its code in an X-Proxies-Error-Code header, and its message names the fix. Other refusals carry the code only in the body. In the build checked on 19 October 2026, the generic Invalid request 400 sends the same header value, so read the body before acting on the header. This is the response we received on 19 October 2026 after pointing an HTTP client at port 7001:
$ curl -x http://user:pass@gw.proxies.sx:7001 http://example.com/
E_WRONG_PORT: you sent an HTTP request to the SOCKS5 port (7001). Use http:// on port 7000, or socks5h:// on port 7001 — the scheme must match the port. e.g. curl -x http://USER:PASS@gw.proxies.sx:7000 | curl --proxy socks5h://USER:PASS@gw.proxies.sx:7001SOCKS5 clients get reply codes instead of text
SOCKS5 has no room for a message body. A refusal on port 7001 arrives as a one-byte status defined by RFC 1928, section 6 (connection replies) or RFC 1929 (username and password). Your client turns that byte into its own wording.
| What the client reports | Byte | Gateway conditions behind it |
|---|---|---|
| Authentication failure, for example curl's User was rejected by the SOCKS5 server (1 1) | RFC 1929 status 0x01 | Any 407 condition: missing or wrong credentials, no balance, key cap reached |
| Connection not allowed by ruleset | 0x02 | Connection or session limit reached, blocked target |
| Host unreachable | 0x04 | No stock for your filters, or the selected endpoint failed |
| General SOCKS server failure | 0x01 | Malformed request |
| Command not supported | 0x07 | BIND or UDP ASSOCIATE. The gateway supports CONNECT only |
To see the full code and message, repeat the request through port 7000 with http:// and the same username. The routing checks are the same on both ports.
What to send support
Send the req id, the UTC time of the failure and the first line of the response. Add the username with the password removed, the port, and the client name and version. The req id lets us find the exact refusal. A screenshot of a browser error cannot, because browsers hide the proxy response (the tunnel failure guide explains why).
For a quick outside check of your connection settings, the proxy tester runs a request with the details you enter. The Pool Gateway page describes the product these codes belong to.
Common questions
Why does curl only print "CONNECT tunnel failed, response 407"?
For an HTTPS URL, curl first asks the proxy to open a tunnel. When the proxy refuses, curl reports the status and does not print the body that holds the code. Run the same command against an http:// URL with -i to read the body.
Does a 502 from the proxy mean the website is down?
Not when the body carries an E_ code. E_NO_STOCK_COUNTRY and E_STOCK_DEGRADED are about our endpoints and your filters, and the request never reached the website. A 502 that arrives after the TLS handshake comes from the website side.
Are these codes stable enough to use in scripts?
Branch on the code and treat the message as text for people. The wording of a message can change, while the codes come from one fixed list in the gateway.
Sources and test scope
Standards and vendor documentation checked on 19 October 2026. Gateway responses on these pages were observed with test requests or read from the gateway build running that day, and the client examples were run against local test servers. They do not establish current stock in a country or how a website will respond.
Connect your application to Proxies.sx
Use the username builder for gateway routing fields and the format converter for existing connection lists. Review Pool Gateway documentation, then check current mobile stock before buying traffic.
For agent-driven workflows, the agent service index lists the supported APIs. A configured HTTP client still needs to validate its task's response.
Proxy error and troubleshooting guides
Start from the symptom table, or open the guide for the error you saw.