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 a trusted IP:

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 Username and password 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 a trusted IP of this service.	Copy the proxy password again from the Username and password 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 a trusted IP.	Send your username and proxy password, or add the address as a trusted IP.
The targeting options in your username are not valid for this service. Check spelling, and do not repeat an option.	An option is misspelt, repeated, not offered by this product (for example city on Unlimited), or its value is malformed or out of range.	Compare the username with the options table. Remove options one at a time to find the one refused.
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; nothing is charged automatically.
This service has used its traffic allowance. Add traffic to continue.	A service with a traffic allowance, such as Residential IPv4 GB-based, 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’s hour has ended.	Buy a plan on the pricing page. 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.

What does a 407 without a reason mean?

After repeated wrong or missing usernames and passwords from one address, the gateway refuses every new connection from that address for 60 seconds, including connections with the correct username and proxy password. Those refusals are a bare 407 with no body and no X-Proxy-Reason. Stop the client, correct the username and proxy password, and wait a minute before trying again.

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. Only one of them carries a reason.

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
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, and every port except 80 and 443 on the free trial	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 IPv4 reaches IPv4 destinations. See Datacenter IPv6.

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.