Connection errors

Start with one cURL request

Before you change your code, test the proxy on its own. If this works, the proxy is fine and the problem is in your client’s setup:

curl -v -x http://USERNAME:PASSWORD@HOST:PORT https://api.ipify.org

The -v output shows each step. Here’s how to read it:

1. Connected to HOST means your network reached the proxy.
2. HTTP/1.1 200 Connection established means the proxy accepted your login and opened a tunnel to the site.
3. The last line is the reply from the site, which should be your Pine IP.

Where the output stops tells you which section below applies.

Connection refused or timed out

Your machine couldn’t reach the proxy at all.

• Compare the host and port with your proxy list, character by character.
• Check that the IP is active on your account. IPs from an expired order stop answering.
• Some office, school and cloud networks block outbound connections on unusual ports. Try from another network, such as a phone hotspot, to rule that out.
• Check that a local firewall or VPN isn’t blocking the connection.

407 Proxy Authentication Required

The proxy is reachable, but it didn’t accept the login.

• Check the username and password for typos and stray spaces.
• URL-encode symbols in the password. @ becomes %40, : becomes %3A and / becomes %2F.
• Check the fingerprint suffix if you use one. It has to be one of -os-macos, -os-ios or -os-linux, in lowercase.
• In Puppeteer, call page.authenticate() before the first goto. See Puppeteer and Playwright.

403 and other errors from the site

A 403, 429 or captcha page comes from the site, not the proxy. The connection worked, and the site chose to turn the request away. Blocked requests covers how to fix that.

TLS and certificate errors

• Use http:// at the start of the proxy URL, even for https:// sites. An https:// proxy scheme makes your client try TLS with the proxy itself, which fails.
• Update your system’s certificate store. In Python, run pip install --upgrade certifi.
• Don’t turn off certificate checks to make an error go away. The proxy passes TLS straight through, so a certificate error means something else is wrong.

The reply shows your own IP

Your request didn’t go through the proxy.

• In Python, set the proxy for both http and https. With only http, secure requests skip the proxy.
• Look for HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables that override your settings.
• Check that the tool supports the scheme you used. Some only take http://, and others need a plugin for socks5h://.

DNS errors over SOCKS5

If hostnames fail to resolve, or resolve differently than they would in the US, switch the scheme from socks5:// to socks5h://. With the h, the proxy looks up the name instead of your machine.

Still stuck

Send support the full output of the curl -v request above, with your password removed. Include the time you ran it.