ScrapingProxies

Python requests ProxyError, Tunnel and SSL Errors: What Each Means and How to Fix It

AE
Engineering desk
Published
November 22, 2026
Reviewed by
Read Time
3 min read
Python requests proxy failures side by side: unreachable proxy, tunnel refused, 407 on CONNECT, a silent 407 response on plain HTTP, and a malformed proxy URL

Short answer: When a request through a proxy fails, Python's requests library raises a handful of exceptions that look similar but point to different problems. ProxyError with "Unable to connect to proxy" means requests never reached the proxy: the host or port is wrong, the proxy is down, or a firewall blocks it. ProxyError with "Tunnel connection failed" followed by a status code means requests reached the proxy, asked it to open a tunnel to an HTTPS site, and the proxy refused; a 407 there means the username or password was rejected. InvalidProxyURL means the proxy string itself is malformed, often a missing http://. The trap is the plain-HTTP case: with a wrong password and an http:// target URL, requests raises nothing and returns a normal response with status code 407. We reproduced each case with requests 2.34 against a local test proxy. The classifier below tells them apart.

What each failure looks like

What you seeMeaningFix
ProxyError: ... Unable to connect to proxy ... NewConnectionErrorThe proxy host or port is unreachableCheck host, port, firewall
ProxyError: ... Tunnel connection failed: 407 Proxy Authentication RequiredWrong login, HTTPS URLFix the username or password
ProxyError: ... Tunnel connection failed: 502 Bad Gateway (or 403, 503)Proxy reached, tunnel refusedCheck the target and retry later
Response with status_code == 407, no exceptionWrong login, plain-HTTP URLCheck the status code
InvalidProxyURL: Please check proxy URLMalformed proxy stringAdd the http:// scheme
ProxyError with a read timeout, https:// proxy URLTLS to a proxy that speaks plain HTTPUse http:// for the proxy URL itself

Two mistakes that cause most of these

The first is the proxy URL scheme. The https key in the proxies dictionary says which target URLs use the proxy; it does not mean the proxy URL should start with https://. Most proxies, Aethyn's included, accept plain HTTP on their HTTP port and tunnel HTTPS traffic through CONNECT. Writing https:// in the proxy URL makes requests try to open TLS to the proxy itself. Against our test proxy that hung until the read timeout and surfaced as a ProxyError. The second is special characters in the password. A password containing @, :, / or # breaks the URL unless it is percent-encoded. urllib.parse.quote(password, safe='') fixes it, and we confirmed the proxy receives the original password. Avoid storing credentials in environment variables or committed files. The requests documentation flags both as a security risk.

A classifier that tells them apart

Code Snippet
from urllib.parse import quote

import requests

USER = "aethyn-XXXXX-country-us"
PASSWORD = "PASSWORD"  # percent-encode it if it contains @ : / or #
proxy = f"http://{USER}:{quote(PASSWORD, safe='')}@proxy.aethyn.io:2099"
proxies = {"http": proxy, "https": proxy}


def fetch(url):
    try:
        r = requests.get(url, proxies=proxies, timeout=(10, 30))
    except requests.exceptions.InvalidProxyURL:
        return "bad proxy URL: check the scheme (http://) and the host"
    except requests.exceptions.SSLError as e:
        return f"TLS failed: {e}"
    except requests.exceptions.ProxyError as e:
        if "Tunnel connection failed: 407" in str(e):
            return "proxy rejected the login (407 on CONNECT)"
        if "Tunnel connection failed" in str(e):
            return "proxy refused the tunnel (CONNECT got a non-200 reply)"
        return "could not reach the proxy: host, port or firewall"
    except requests.exceptions.ConnectTimeout:
        return "connect timed out: safe to retry"
    if r.status_code == 407:
        return "proxy rejected the login (407 on a plain-HTTP URL)"
    return r

The code on this page was run on November 22, 2026 against a local stand-in proxy that checks the login (Chromium 149, requests 2.34, Selenium 4.53, Puppeteer 25.18), not against live targets or the Aethyn gateway. Replace aethyn-XXXXX and PASSWORD with your own credentials.

The order of the except clauses matters. In requests 2.34, ProxyError and SSLError both subclass ConnectionError, so catch them before any broader handler. ConnectTimeout is the one that requests documents as safe to retry.

SOCKS5 with requests

Install the extra with pip install "requests[socks]", then use socks5h:// rather than socks5:// so DNS is resolved by the proxy, not on your machine. The same rule applies in aiohttp with SOCKS5. Aethyn's SOCKS5 ports are 1099 on Premium and 3499 on Elite, with the same credentials as HTTP.

FAQ

Python requests proxy error questions

What does requests.exceptions.ProxyError mean?
requests could not complete the request through the proxy. The message says why: “Unable to connect to proxy” with a NewConnectionError means the proxy host or port was unreachable, and “Tunnel connection failed: 407” or another status means the proxy refused the CONNECT for an HTTPS URL.
Why does my wrong proxy password not raise an exception?
For a plain http:// URL, requests sends the request to the proxy directly, and the proxy's 407 comes back as an ordinary response. requests returns it with status_code 407 and raises nothing, so code that only catches exceptions treats it as success. Check the status code.
How do I use a proxy password with special characters in requests?
Percent-encode the password before putting it in the proxy URL, for example with urllib.parse.quote(password, safe=''). We confirmed the proxy then receives the original password, including @, : and /.
Is ProxyError a subclass of ConnectionError?
Yes. In requests 2.34, ProxyError and SSLError both subclass ConnectionError, which subclasses RequestException. Catch ProxyError before ConnectionError if you want to handle it separately.
Share this article

Guides, integrations & docs

Continue reading

A proxy URL that just works in requests

http://USER:PASS@proxy.aethyn.io:2099 for Premium, port 5499 for Elite. SOCKS5 on 1099 and 3499 with requests[socks].

Back to all articles