Skip to content

Guides · Connect and debug

Proxy errors: find the right fix

Most proxy errors fall into four stages: the client cannot reach the proxy, the proxy asks for credentials (407), the proxy refuses the tunnel (403, 502 or 503), or the destination itself fails after the tunnel opens. Keep the exact error text, client version and failing stage. Then choose the matching guide below. A browser connection error, an HTTP proxy response and a Python exception are different kinds of evidence; the same number or word can require a different check in another client.

By PortproofPublished Updated

Short answers

Which proxy error should I investigate first?

Use the most specific message you have: a browser code, curl’s complete error line, a Python exception with its underlying cause, or a gateway code. Identify whether the client reached the proxy before changing authentication or the destination request.

Is 407 the same as a connection refusal?

No. HTTP 407 is a proxy authentication response. A refused connection can happen before an HTTP response is received. The 407 and connection-refused guides below follow those stages separately.

What if curl works and my app does not?

Compare the same gateway, destination and credentials in the actual application process. It may use different environment variables, exclusions, transport settings or saved credentials. Start with the curl-versus-app guide, then use the guide for your client.

Browser messages and sign-in prompts

Choose the guide matching your screen
What you seeFocused guide
The proxy requires a username and password (Chrome, Edge) or The proxy moz-proxy://… is requesting a username and password (Firefox)Identify the proxy and choose its credentials.
Firefox: The proxy server is refusing connectionsCheck Firefox’s proxy mode, host, port and local proxy app.
Firefox: Unable to find the proxy serverCheck the proxy hostname and your network connection.
Chrome: ERR_PROXY_CONNECTION_FAILEDCheck proxy name resolution, host, port and route.
Chrome: ERR_MANDATORY_PROXY_CONFIGURATION_FAILEDCheck the required PAC configuration.
Chrome or Edge: ERR_TUNNEL_CONNECTION_FAILEDFind the proxy in use and read its CONNECT answer.
Firefox ignores or keeps a proxy you changedCheck Firefox’s own connection settings.
A proxy setting you do not recogniseUnderstand manual, PAC and automatic settings.

curl messages and exit codes

Match the message as well as the number. Error text can include the proxy or the destination hostname, and curl releases can assign different exit codes to a failed CONNECT. The linked guides include their recorded versions and local fixture scope.

Find the failing stage in curl
What you seeFocused guide
Could not resolve proxy or Could not resolve host naming the gatewayCheck the gateway hostname and DNS.
Failed to connect / Couldn't connect to serverCheck a refused port and network reachability.
Timeout was reached, a connection timeout or an unanswered proxy handshakeDistinguish connection and handshake timeouts.
CONNECT tunnel failed, response 407Check proxy authentication and balance.
CONNECT tunnel failed, response 403, 502 or 503Read the CONNECT status and gateway evidence.
User was rejected by the SOCKS5 serverCheck SOCKS5 authentication and the matching port.
SSL certificate problemCheck the certificate stage with verification enabled.
429 Too Many RequestsIdentify the responding service and respect its retry timing.
No clear error, but the route or exit IP is unexpectedRun one explicit proxy check.
The exit IP reports an unexpected countryCheck the requested country and the lookup source.
A sticky session returned a different IPCheck session names and carrier changes.

Python, Node.js and app failures

Use the diagnostic for the actual client
Client and messageFocused guide
Requests: ProxyError, ConnectionError, ConnectTimeout or ReadTimeoutRequests proxy exception checks.
Requests: SSLErrorRequests certificate and environment checks.
HTTPX: ProxyError, ConnectError or HTTPStatusErrorHTTPX transport and response checks.
urllib: URLError with a tunnel message, or HTTPError 407urllib routing and gateway checks.
Java or app logs: Unable to tunnel through proxy, CONNECT refused by proxy or failed to complete tunnel connectionRead the CONNECT status behind the message.
aiohttp: ClientProxyConnectionError, ClientConnectorDNSError or ConnectionTimeoutErroraiohttp connection diagnostics.
aiohttp: ClientHttpProxyError or ClientConnectorCertificateErroraiohttp tunnel and certificate checks.
Node.js: TypeError: fetch failedInspect the underlying cause and dispatcher.
The proxy works in curl but fails in the appCompare process settings and proxy exclusions.
pip, npm, Git or Docker ignores the proxyCheck the tool’s own settings: pip, npm, Git or Docker.

An exception class is a starting point. Keep its cause and response status when available. A returned website status is different from a client failing before it receives that response; follow the linked client guide to identify the stage.

Portproof gateway codes

Use these only when the gateway actually reports the detailed code. A bare 407 or 502 cannot establish the corresponding cause by itself. The setup reference lists the documented gateway responses.

Documented codes and next steps
Status and codeFocused next step
407 · auth_failedCheck the full generated username and proxy password.
407 · quota_reachedCheck remaining GB and traffic validity.
400 · bad_usernameRebuild the username with accepted tokens.
429 · too_many_connectionsReview parallel connections and bounded retry decisions.
429 · too_many_sessionsReview named sessions and intended reuse.
502 · no_exit_availableCheck current availability for the chosen pool and country.

If the message is not listed

Start with the curl check against a small authorised endpoint. Record the UTC time, client version, proxy scheme, host and port without credentials, exact message, CONNECT status and destination status when available. Keep passwords, API keys and credential-bearing URLs out of shared logs. That report helps establish which guide or support check applies.

Sources and scope

References checked on 4 October 2026: Chromium error definitions, Firefox error strings, curl error reference, Requests exceptions, HTTPX exceptions, aiohttp exceptions and Undici’s fetch error handling. This directory adds navigation; test evidence remains in each linked guide.

What is not allowed

Use diagnostics only for permitted services and follow the acceptable-use policy.

More in Connect and debug

Show 25 more

Buy mobile and residential proxy GB

Choose your GB or reserve a mobile device.

Buy pool GB Try 1 GB for EUR 1.49

Once per customer. Cryptocurrency network minimums and fees vary.