Proxy errors and refusal reasons

When TrueProxies refuses an HTTP or HTTPS proxy connection, it answers 407 Proxy Authentication Required with a one-sentence reason in the body and in the X-Proxy-Reason header. SOCKS5 has no field for text, so the handshake fails instead. The tables below list every reason, when it happens, and what to do.

What does a refused request look like?

This is the whole answer to a request sent with no username or password from an address that is not on the service’s IP whitelist:

HTTP/1.1 407 Proxy Authentication Required
Content-Length: 79
Connection: close
Content-Type: text/plain; charset=utf-8
Proxy-Authenticate: Basic realm="proxy"
Proxy-Connection: close
X-Proxy-Reason: No credentials sent, and this address is not on the service's trusted IP list.

No credentials sent, and this address is not on the service's trusted IP list.

Port	How a refusal arrives
HTTP and HTTPS (CONNECT or a plain http:// request)	407 Proxy Authentication Required. The reason is the response body and the X-Proxy-Reason header, and the gateway closes the connection.
SOCKS5	The username and password step fails, the same way for every reason, and the connection closes. A client that sends no username and password sees the connection close before its CONNECT is answered. No reason text is sent.

Refusals are decided before an exit is chosen, so a refused connection uses no traffic.

How do I see the reason from my client?

Many clients report only the status line. Python’s standard library, for example, raises Tunnel connection failed: 407 Proxy Authentication Required for an HTTPS URL, and a browser shows a generic proxy error. Send the same request with curl -v and read the X-Proxy-Reason line:

curl -v -x http://YOUR_HOST:YOUR_HTTP_PORT \
  -U "YOUR_USERNAME:YOUR_PASSWORD" \
  https://httpbin.org/ip 2>&1 | grep -i "x-proxy-reason"

For SOCKS5, send the same username and proxy password once through the HTTP port with curl -v to read which part was refused.

What does each refusal reason mean?

The first column is exactly what the gateway sends, in the body and in X-Proxy-Reason. Every row answers with 407.

Reason	When it happens	What to do
Username not recognised. Check the username on your service page.	The part of the username before any options does not have the shape of a TrueProxies username, or a password was sent with an empty username.	Copy the username again from the Proxy setup tab. Add options after it with hyphens, as in YOUR_USERNAME-country-de.
Username not recognised, or the service it belongs to has ended. Check your service page.	The username is well formed, but no current service uses it: a typo, or the service is Closed.	Check that the service is listed under Current in the dashboard, then copy its username again.
Wrong proxy password. Check the credentials on your service page.	The proxy password does not match, or no password was sent from an address that is not on this service’s IP whitelist.	Copy the proxy password again from the Proxy setup tab. After Change password, the old password keeps working for 2 minutes.
No credentials sent, and this address is not on the service's trusted IP list.	The request carried no username or password, and its source address is not on the service’s IP whitelist.	Send your username and proxy password, or add the address to the IP whitelist.
The targeting options in your username are not valid for this service. Check spelling, and do not repeat an option.	An option is misspelt or repeated, or its value is malformed.	Compare the username with the options table. Remove options one at a time to find the one refused.
Session IDs can use letters and digits only, up to 32 characters, with no dashes or underscores.	The session value has a character other than a letter or digit, or more than 32 characters. A dash inside a session ID ends it, so the rest is read as an option.	Use 1 to 32 letters or digits, as in YOUR_USERNAME-session-abc123.
Session lifetime must be whole seconds within this service's range and needs a session ID, for example -session-abc123-lifetime-1800.	lifetime is not a whole number, is outside the range in the options table, or was sent without session.	Send lifetime after session, in seconds within your product’s range.
This service does not offer city targeting. Remove -city- from the username. (each option has its own line naming it; without one: Your username uses an option this service does not offer. Use the options shown in Proxy setup on your service page.)	The option exists but your service does not offer it, for example region on Unlimited Standard or asn on Unlimited Pro, or lifetime on a service without Set session lifetime.	Remove the option the message names. Proxy setup on your service page shows only the options your service accepts.
This service is not currently serving.	The service is not in a state that carries traffic, for example while it is Activating, or the gateway is briefly not accepting new connections.	Check the service’s status in the dashboard. If it is Active, retry after a few seconds. If the answer persists, contact Support.
This service is suspended. Contact support to resolve it.	The service is Suspended.	Contact Support.
This service has reached its expiry date. Renew it to continue.	The service’s paid period has ended and it shows Renewal due.	Pay the renewal invoice in the dashboard. Renewals raise an invoice; it is charged to the saved card only when Automatic renewal is on, otherwise you pay it.
This service has used its traffic allowance. Add traffic to continue.	A service with a traffic allowance, such as a Residential IPv4 Standard, Premium or Lite traffic pack, has used all of its traffic, or the project the username belongs to has used its traffic budget.	Add a traffic pack to the service with Top-up, or raise the project’s traffic budget.
This free comparison is closed. Check your service page.	A free comparison reached its fixed end time or used its traffic allowance.	A free comparison cannot be renewed or topped up. Buy a plan on the pricing page to continue.
Your trial has closed. Buy a paid plan to continue.	The free trial has ended. A trial that has ended cannot be started again.	Buy a plan on the pricing page. To keep testing, a 1-hour Unlimited Standard plan at 10 Mbps costs $4.08. A paid plan is a separate service with its own username and proxy password.
This service is temporarily unavailable. Try again in a moment.	The free trial could not start on its first connection, or the gateway cannot confirm traffic used by a service with a traffic allowance.	Retry after a few seconds, backing off between attempts. If it lasts more than a few minutes, contact Support.
Too many new connections per second for this service's limit.	New connections arrived faster than the service’s limit on connections opened per second.	Reuse connections with keep-alive or a connection pool, and spread new connections over time.
This service is at its maximum number of open connections.	The service already has as many open connections as its plan allows.	Close idle connections or lower your client’s concurrency.
The proxy is at capacity right now. Try again in a moment.	The gateway is full right now. This is not a limit on your service.	Retry after a few seconds, backing off between attempts.
Too many wrong usernames or passwords from this address in the last minute. Correct logins still connect; check the username and proxy password on every client at this address.	20 or more connections with a wrong username or proxy password arrived from one address within a minute. For 60 seconds the gateway then refuses further wrong logins from that address at once. Connections with the correct username and proxy password, and connections from a whitelisted IP, still connect. A common cause is a worker still using the username of a service that has ended.	Stop every client at that address that still sends an old or wrong username or proxy password. The lockout ends on its own a minute after the wrong logins stop.
This port belongs to another service.	The connection reached a sticky port or a Static ISP IP port that belongs to a different service than the username.	Copy the port list again from the Proxy setup tab of the service whose username you send.
The network behind this service is refusing its connections right now. New connections pause for a minute; check the traffic left on your service page, and contact support if it shows traffic.	The residential network behind the service refused its connections, for example because its traffic ran out there. New connections pause for a minute.	Check Traffic remaining on the service page. If it shows traffic, contact Support.
Nearly every connection from this service failed to reach its destination (N of M in the last two minutes). New connections are paused for S seconds. Slow down, and check the destinations your client requests.	Almost every recent connection from the service failed at the destination: a dead site, a closed port or a flood of retries. New connections pause briefly so the failures do not take the network down for everyone.	Slow your client down, and check the hostnames and ports it requests. The pause ends on its own.

Why was a connection refused after it authenticated?

These answers come after the username and proxy password were accepted, when the gateway could not open a route to the destination. On the HTTP and HTTPS ports, the ones with a reason carry it in the body and in X-Proxy-Reason. SOCKS5 has no field for text and sends only its reply code.

Situation	HTTP and HTTPS ports	SOCKS5 reply
A Datacenter IPv6 service asked for a destination that has no IPv6 address	502 Bad Gateway with the reason Datacenter IPv6 proxies reach IPv6 destinations only. This destination has no IPv6 address.	0x03, network unreachable
A Residential IPv6 service asked for a destination that has no IPv6 address, past the IPv4 fallback limits	502 Bad Gateway with the reason Residential IPv6 proxies reach IPv6 destinations only. This destination has no IPv6 address.	0x03, network unreachable
A Residential IPv4 service asked for a name that has no IPv4 address. The gateway learns this after the first silent attempt, then refuses at once	502 Bad Gateway with the reason IPv4 proxies reach IPv4 destinations only. This destination has no IPv4 address.	0x03, network unreachable
The name does not exist (its DNS answer is NXDOMAIN). Learned after one failed attempt, then refused at once	502 Bad Gateway with the reason Destination not found. This name does not exist.	0x03, network unreachable
A sticky session’s IP still works for other sites, but this site did not answer through it. The session keeps its IP	502 Bad Gateway with the reason No response. The destination did not answer through this IP. Your sticky session keeps its IP; retry the request.	0x03, network unreachable
A plain http:// request got no answer from the site in time	503 Service Unavailable with the reason No response. The destination did not answer through this IP in time. Retry the request.	—
The service has the IP reputation filter on and no exit for this session passed the check within five tries	502 Bad Gateway with the reason No clean IP found for this session. Retry, or use a new session name. (or IP check unavailable. Retry shortly. when the check could not be answered)	0x03, network unreachable
The destination is a private or reserved address, such as 127.0.0.1 or 192.168.0.0/16, or a destination TrueProxies blocks	403 Forbidden, no reason	0x02, connection not allowed by ruleset
The destination port is closed: mail ports 25, 465, 587 and 2525 on every service	503 Service Unavailable, no reason	0x03, network unreachable
No exit is free right now for the requested targeting, or the destination refused, reset or did not answer the connection	503 Service Unavailable, no reason	0x03, network unreachable

A Datacenter IPv6 service reaches only destinations with an IPv6 address. Check the destination with dig AAAA example.com +short; an empty answer means it cannot be reached from that product. Residential IPv6 opens such sites through its IPv4 fallback, within fair-use limits. Residential IPv4 reaches IPv4 destinations. See Datacenter IPv6 and Residential IPv6.

Usage history on the service page lists Destination has no IPv4 address, Destination has no IPv6 address and Destination not found under Not counted against success: no proxy can reach those destinations, so they do not lower your connection success.

A 503 for a country that is a valid ISO 3166-1 code is a coverage miss, not a bad request: the same username can succeed later without changes.

Which errors come from the destination site?

Once a CONNECT tunnel is open (200 Connection established), every status code inside it comes from the website, not from TrueProxies. A 403 or 429 returned by the site, or a TLS error from the site, is the site’s own answer to that request and exit. The same applies to a plain http:// request: the gateway passes the site’s response through. A 407 or a failed CONNECT is the gateway’s answer, described above.

What should I send to support?

Include the reason text, the HTTP status or SOCKS5 reply, the UTC time, the product, the protocol and the destination hostname. Never include the proxy password. See the support checklist.