Troubleshooting the WinError 10061 with Python Requests

Have you ever encountered the cryptic WinError 10061 when trying to use Python's requests module to retrieve a web page or API data? This error is frustratingly vague, but with a few tweaks you can get past it.

What Does WinError 10061 Mean?

The full error looks something like:

requests.exceptions.ConnectionError: 
HTTPSConnectionPool(host='api.example.com', port=443): 
Max retries exceeded with url: /data 
(Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x1012345>: 
Failed to establish a new connection: [WinError 10061] No connection could be made because the target machine actively refused it'))

The key part is Failed to establish a new connection: [WinError 10061]. This is a Windows-specific error indicating the remote server actively refused the connection attempt.

Some common reasons this can happen:

Confirm the Server is Responding

First, confirm you have the correct URL and that the server is actually responding.

Try making the request from a browser or tool like cURL. If those fail too, there is likely an issue with the server or network.

If the URL loads fine externally, continue troubleshooting Python.

Check for Proxy or Firewall Issues

Enterprise networks sometimes interfere with Python's default HTTP handling.

Try setting proxy information in your script if required by your network:

proxies = {
  'https': 'http://10.10.1.10:3128'  
}

requests.get(url, proxies=proxies)

You may also need to whitelist the server's domain in firewall policies if they are blocking unauthorized connections.

Verify TLS Versions

Modern sites require TLS 1.2 or higher. If you get errors about "SSL: CERTIFICATE_VERIFY_FAILED", Python may be defaulting to an outdated TLS version:

SSLError(SSLError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:852)'),)

Specify TLS 1.2 or higher explicitly:

import requests
requests.get(url, tls.TLSVersion.TLSv1_2) 

Check Name Resolution

One overlooked cause of connection issues stems from name resolution problems.

Verify Python can resolve the hostname to an IP address:

> import socket
> socket.gethostbyname('api.example.com')
'93.184.216.34'

If this fails, there is likely a DNS server configuration issue, which may require network admin assistance to fix.

Enable Debug Logging

Finally, for stubborn problems enable full debugging logs in requests and see if that reveals anything:

import logging
import http.client as http_client

http_client.HTTPConnection.debuglevel = 1

logging.basicConfig() 
logging.getLogger().setLevel(logging.DEBUG)
requests_log = logging.getLogger("requests.packages.urllib3")
requests_log.setLevel(logging.DEBUG)
requests_log.propagate = True

requests.get(url)  

Check logs for hints like incorrect hostnames or TLS issues.

When All Else Fails...

If you still get WinError 10061 after all this, some other environmental issue may be interfering.

As a last resort, try running your Python code from a different machine on the same network. If that works, compare configurations between machines that pass and fail. This can help narrow down external factors causing problems.