Analytics cookies

May we use Google Analytics to see which pages are read, how visitors find this site and whether visits lead to an account or a purchase? It sets cookies and sends Google details of your visit, including your IP address. Google Analytics loads only if you accept, and you can change your choice at any time under Cookie settings at the bottom of the page. Privacy notice

Portproof
Menu

Guides · Connect and debug

Proxy errors: find the right fix

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.

All guides

Published

On this page

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 passwordIdentify the proxy and choose its credentials.
Firefox: The proxy server is refusing connectionsCheck the selected proxy’s reachability.
Chrome: ERR_PROXY_CONNECTION_FAILEDCheck proxy name resolution, host, port and route.
Chrome: ERR_MANDATORY_PROXY_CONFIGURATION_FAILEDCheck the required PAC configuration.
Chrome: ERR_TUNNEL_CONNECTION_FAILEDSeparate CONNECT failure from a website response.
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.
No clear error, but the route or exit IP is unexpectedRun one explicit proxy check.

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.
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.

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 · E_AUTH_INVALIDCheck the full generated username and proxy password.
407 · E_CAP_EXCEEDEDCheck remaining GB and traffic validity.
400 · E_USERNAME_PARSERebuild the username with accepted tokens.
429 · E_RATE_LIMITED_CONNReview parallel connection limits and retry guidance.
429 · E_SESSION_LIMITReview named sessions and intended reuse.
502 · E_NO_STOCK_COUNTRYCheck 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.

View proxy optionsSee pricing per GBRead the setup docsAll guides
Proxy errors: find the cause and next check · Portproof