Start by asking: proxy or target?
Every proxy error comes from one of two places: the proxy (your connection to it, your authentication, or its connection onward) or the target website (blocking or rate-limiting you). The fastest way to tell is to run the same request through curl -v and see whether the error happens at the CONNECT stage or after. See curl proxy.
Error reference
| Error | Source | Most likely cause | Fix |
|---|---|---|---|
| 407 Proxy Authentication Required | Proxy | Wrong or missing credentials; IP not whitelisted | Check credentials, URL-encode special characters, update whitelist |
| ERR_PROXY_CONNECTION_FAILED / ECONNREFUSED | Proxy | Wrong host/port, proxy down, firewall | Verify endpoint, try nc -vz host port, check firewall |
| ERR_TUNNEL_CONNECTION_FAILED | Proxy | CONNECT refused (auth, blocked target, provider restriction) | Check auth; ask provider if the target domain is restricted |
| 502 Bad Gateway | Proxy | Exit node or upstream failed | Retry with a new session/IP |
| 503 Service Unavailable | Proxy or target | Overloaded proxy, or target throttling | Back off, rotate |
| 504 Gateway Timeout | Proxy | Exit took too long to reach target | Increase timeout, rotate, choose closer exits |
| 403 Forbidden | Target | Blocked by the site | Change IP type, fix fingerprint, slow down |
| 429 Too Many Requests | Target | Rate limited | Respect Retry-After, spread load, rotate |
| Timeouts | Either | Slow exit, overloaded client, network issues | Rotate, tune timeouts, check your server |
| SSL/TLS errors | Proxy | TLS-intercepting product (unblocker) or MITM | Use provider's CA or verify=False only for trusted unblockers |
| ERR_SOCKS_CONNECTION_FAILED | Proxy | SOCKS auth unsupported in client, wrong port | Whitelist IP, use forwarder, check port |
| CAPTCHA page with 200 OK | Target | Soft block | See CAPTCHAs and proxies |
407 in depth
- Typos and spaces in username or password.
- Special characters not URL-encoded (
@→%40,:→%3A,#→%23). - The client isn't sending credentials (Chrome's
--proxy-serverflag ignores them). - Your plan has expired or run out of traffic.
- You're using a whitelisting port with credentials or vice versa.
- Your public IP changed and isn't whitelisted.
See proxy authentication methods and Puppeteer proxy authentication.
Connection refused vs timeout
- Refused: something actively rejected the connection: wrong port, nothing listening, or a protocol mismatch (HTTP to a SOCKS port).
- Timeout: packets aren't getting through: firewall, wrong IP, or the proxy is down.
nc -vz gate.example.com 7777403 and 429: it's the target
The proxy is working; the target doesn't like the request. Fixes:
- Use a more trusted IP type. See residential vs datacenter proxies.
- Slow down per domain. See rate limiting and proxies.
- Fix headers and TLS fingerprints. See browser fingerprinting and proxies.
- Rotate to a fresh IP after a block.
See avoiding IP bans when scraping.
Proxy tip: If you need a working proxy to test these steps with, Geonode generates endpoints in host:port:username:password format, supports IP whitelisting, and has a Chrome extension for quick switching. See using Geonode in your browser.
502/504: exit node problems
With residential and mobile proxies, exit devices can be slow or drop. Retry with a new session ID. If errors persist in one country or ASN, try broader targeting or contact the provider.
SSL errors
- If you use a web unblocker that re-encrypts traffic, install the provider's CA certificate or disable verification for that client only.
- If you see certificate errors through an ordinary proxy, be suspicious: something may be intercepting your traffic.
Language-specific gotchas
- Python requests: dict keys must be
"http"and"https"; installrequests[socks]for SOCKS. See Python requests proxies. - Node axios: use
https-proxy-agentwithproxy: falsefor HTTPS targets. See Node.js proxies. - curl: lowercase
http_proxyonly. See curl proxy. - Selenium/Chrome: no credentials in the flag. See Selenium proxies.
A step-by-step diagnostic flow
- Can you reach the proxy?
nc -vz host port. If not: host, port, firewall. - Does authentication work?
curl -v -x ... https://api.ipify.org. A 407 means credentials or whitelist. - Does a simple HTTPS site work? If not: CONNECT blocked or provider restriction.
- Does your target work? If not: target blocking; check IP type, rate and fingerprint.
- Does it work in curl but not your code? Library configuration issue.
The exact messages, by tool
Error text varies by tool, which makes searching for help harder. Here's how the most common problems actually appear:
| Tool | Message you'll see | Usually means |
|---|---|---|
| curl | (7) Failed to connect to ... | Wrong host or port, proxy down, or firewall |
| curl | (56) CONNECT tunnel failed, response 407 | Proxy credentials missing or wrong |
| curl | (97) Proxy handshake error | SOCKS handshake failed: wrong port, protocol or credentials |
| Python requests | ProxyError ... Unable to connect to proxy | Wrong host or port, or firewall |
| Python requests | Tunnel connection failed: 407 Proxy Authentication Required | Credentials, often a special character not URL-encoded |
| Python requests | InvalidSchema: Missing dependencies for SOCKS support | Install requests[socks] |
| Python requests | SSLError ... CERTIFICATE_VERIFY_FAILED | An intercepting proxy or corporate TLS inspection |
| Node.js (undici) | Proxy response (407) !== 200 when HTTP Tunneling | Credentials missing or wrong |
| Node.js | ECONNREFUSED, ETIMEDOUT, ECONNRESET | Endpoint, timeout or dropped connection, as in the table above |
Two tips make any of these faster to solve:
- Reproduce with curl
-v. If curl shows the same failure with the same proxy, the problem is the proxy or your network, not your code. - Copy the full message when asking for help, with the tool and version. "It doesn't work" can't be searched;
(56) CONNECT tunnel failed, response 407can.
For credentials problems in depth, see proxy authentication methods. For language specifics, see Python requests proxies and Node.js proxies, and for curl itself, curl proxy.
FAQ
How do I know if the proxy or the website is blocking me?
If the error occurs before the tunnel is established (407, connection refused, tunnel failed), it's the proxy. If you get a response from the site (403, 429, CAPTCHA), it's the target.
Why do errors happen only at certain times?
Residential pools fluctuate with time zones, and targets may tighten protection at peak times.
Editorial note: Proxy providers change their pools, features and prices often, so treat any figures here as typical ranges at the time of writing and confirm current terms with the provider before you buy.