Fix: Python requests.exceptions.ConnectionError: Max retries exceeded

The Error

You run a Python script using the requests library and get:

requests.exceptions.ConnectionError: HTTPSConnectionPool(host='api.example.com', port=443):
Max retries exceeded with url: /endpoint
(Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at 0x...>:
Failed to establish a new connection: [Errno -2] Name or service not known'))

Or variations:

requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=8080):
Max retries exceeded with url: /api/data
(Caused by NewConnectionError('... [Errno 111] Connection refused'))

requests.exceptions.ConnectionError: HTTPSConnectionPool(host='api.example.com', port=443):
Max retries exceeded with url: /endpoint
(Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED]')))

urllib3.exceptions.MaxRetryError: HTTPSConnectionPool(host='...', port=443):
Max retries exceeded with url: /path

The requests library tried to connect to a server multiple times and failed every time. The underlying cause is in the parenthetical message after “Caused by.”

Why This Happens

The requests library (via urllib3) automatically retries failed connections. When all retries are exhausted, it raises ConnectionError with “Max retries exceeded.” The real error is the nested cause wrapped inside the exception, not the outer message itself. Reading only the top line is the most common reason developers get stuck — every fix below depends on which inner error you actually have.

Common causes (look at the “Caused by” message):

• Name or service not known / getaddrinfo failed — DNS resolution failed. The hostname does not exist or DNS is unreachable.
• Connection refused — The server is not running or not listening on that port.
• Connection timed out — The server is unreachable (firewall, wrong IP, network issue).
• SSLError / CERTIFICATE_VERIFY_FAILED — SSL/TLS certificate verification failed.
• Too many open files — Connection pool or file descriptor exhaustion.
• Network is unreachable — No network connectivity at all.

There is also a subtler structural cause. By default requests uses zero urllib3 retries on connection-level failures, but it does retry on transport-level events like dropped connections during keep-alive. If you mount a custom adapter with Retry(total=5, ...) and a downstream service starts returning 503, requests quietly retries five times before raising. That means a “Max retries exceeded” error that took 30+ seconds to appear is usually a downstream slowness or intermittent failure, not a hard misconfiguration. Distinguishing fast failures (millisecond — DNS, refused) from slow ones (multi-second — timeout, downstream 5xx) is the single best heuristic for picking the right fix.

In Production: Incident Lens

In production this error means a dependency has degraded. The downstream service is slow, returning 503s, or unreachable; your client exhausts its retry budget and fails the request. The blast radius depends entirely on which dependency. If the failed call is to your auth service, every request fails and the incident is global. If it is to a recommendations service that you wrap in a cache fallback, the user sees stale recommendations and no one pages.

The monitoring signal is downstream-side first: error rate and 99p latency on the upstream service the client is calling. On the client side, watch outbound HTTP error rate per host, retry count per request, and saturation of the connection pool. A spike in retry count without a corresponding spike in actual failures means your client is masking the issue and burning latency budget — the request eventually succeeds but takes 10x longer. The correct alert is on the ratio of retried-then-succeeded requests, not just on outright failures.

Recovery is circuit breaking: detect the elevated error rate and stop sending new requests for a cool-down window, returning a fallback or a fast 503 instead. Without a breaker, every caller piles into the dying dependency, exhausts your thread pool, and the failure spreads to unrelated endpoints. Postmortem preventives are a strict timeout budget (every outbound call has both a connect and read timeout, and the sum is less than the parent request’s deadline), retry with jitter (do not retry instantly; spread the retries with random backoff so all clients do not slam the recovering service simultaneously), and a bulkhead (cap concurrent calls per dependency so one slow service cannot exhaust your whole worker pool).

Fix 1: Check the URL

The most common cause is a wrong URL:

import requests

# Wrong — typo in hostname
response = requests.get("https://api.exmple.com/data")  # "exmple" not "example"

# Wrong — HTTP vs HTTPS
response = requests.get("https://localhost:8080/api")  # Server only supports HTTP
response = requests.get("http://localhost:8080/api")   # Fixed

# Wrong — missing port
response = requests.get("http://localhost/api")   # Tries port 80, server is on 8080
response = requests.get("http://localhost:8080/api")  # Fixed

# Wrong — trailing slash matters for some APIs
response = requests.get("https://api.example.com/users")
response = requests.get("https://api.example.com/users/")  # Try with/without

Verify the URL is reachable:

# Test from the command line
curl -v https://api.example.com/endpoint
ping api.example.com
nslookup api.example.com

Pro Tip: Always print or log the full URL before making the request during development. Many “Max retries exceeded” errors come from a simple typo, an empty variable in an f-string, or a misconfigured base URL.

Fix 2: Check if the Server is Running

If the error says “Connection refused”:

# The server at localhost:8080 is not running
requests.get("http://localhost:8080/api")
# ConnectionError: ... Connection refused

Check the server:

# Is the process running?
ps aux | grep my_server

# Is something listening on the port?
ss -tlnp | grep 8080
# or
netstat -tlnp | grep 8080

# Start the server
python manage.py runserver 0.0.0.0:8080

For Docker services:

docker ps  # Check if the container is running
docker logs my-container  # Check for startup errors

Common in development: You started your client script before the server finished starting up. Add a startup delay or retry logic.

Fix 3: Add Retry Logic with Backoff

For transient network issues, add proper retry handling:

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

session = requests.Session()

retries = Retry(
    total=5,              # Total number of retries
    backoff_factor=1,     # Wait 1, 2, 4, 8, 16 seconds between retries
    status_forcelist=[500, 502, 503, 504],  # Retry on these HTTP status codes
    allowed_methods=["GET", "POST"],         # Which methods to retry
)

adapter = HTTPAdapter(max_retries=retries)
session.mount("http://", adapter)
session.mount("https://", adapter)

response = session.get("https://api.example.com/data", timeout=10)

Simple retry with exponential backoff:

import time
import requests

def fetch_with_retry(url, max_retries=3, timeout=10):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, timeout=timeout)
            response.raise_for_status()
            return response
        except requests.exceptions.ConnectionError as e:
            if attempt < max_retries - 1:
                wait = 2 ** attempt  # 1, 2, 4 seconds
                print(f"Connection failed, retrying in {wait}s...")
                time.sleep(wait)
            else:
                raise

Common Mistake: Not setting a timeout on requests. Without a timeout, requests.get() can hang indefinitely waiting for a response. Always set both connect and read timeouts: requests.get(url, timeout=(5, 30)) — 5 seconds to connect, 30 seconds to read.

Fix 4: Fix SSL Certificate Errors

If the error contains SSLError or CERTIFICATE_VERIFY_FAILED:

# Quick fix for development — disable SSL verification
response = requests.get("https://api.example.com/data", verify=False)
# Warning: This disables ALL certificate checks — never use in production!

Proper fix — specify the CA bundle:

response = requests.get("https://api.example.com/data", verify="/path/to/ca-bundle.crt")

Fix — update certifi (Python’s CA bundle):

pip install --upgrade certifi

Fix — install system certificates:

# macOS
/Applications/Python\ 3.x/Install\ Certificates.command

# Linux
sudo apt install ca-certificates
sudo update-ca-certificates

# pip behind corporate proxy with custom CA
pip install --cert /path/to/corporate-ca.pem requests

For self-signed certificates:

# Add the self-signed cert to the trusted bundle
import certifi
import os

# Option 1: Point to your certificate
response = requests.get("https://internal-api.company.com", verify="/path/to/self-signed.crt")

# Option 2: Set environment variable
os.environ["REQUESTS_CA_BUNDLE"] = "/path/to/custom-ca-bundle.crt"

For general SSL certificate issues, see Fix: Python SSL certificate verify failed.

Fix 5: Fix DNS Resolution Issues

If the error says “Name or service not known” or “getaddrinfo failed”:

# Test DNS resolution
import socket

try:
    ip = socket.gethostbyname("api.example.com")
    print(f"Resolved to: {ip}")
except socket.gaierror as e:
    print(f"DNS resolution failed: {e}")

Common DNS fixes:

# Check DNS resolution
nslookup api.example.com
dig api.example.com

# Flush DNS cache
# Linux
sudo systemd-resolve --flush-caches
# macOS
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
# Windows
ipconfig /flushdns

For Docker containers — DNS might not work:

# docker-compose.yml
services:
  app:
    dns:
      - 8.8.8.8
      - 8.8.4.4

Use IP address instead of hostname as a workaround:

# If DNS is the issue, connect directly to the IP
response = requests.get("https://93.184.216.34/data",
                        headers={"Host": "api.example.com"})

Fix 6: Fix Connection Pool Exhaustion

If you make many requests in rapid succession, the connection pool can run out:

# Wrong — creates a new session for every request
for url in thousands_of_urls:
    response = requests.get(url)  # Each creates a new connection

# Fixed — reuse a session
session = requests.Session()
for url in thousands_of_urls:
    response = session.get(url)  # Reuses connections via keep-alive

Increase the pool size for concurrent requests:

from requests.adapters import HTTPAdapter

session = requests.Session()
adapter = HTTPAdapter(
    pool_connections=20,   # Number of connection pools
    pool_maxsize=20,       # Connections per pool
)
session.mount("http://", adapter)
session.mount("https://", adapter)

Close connections properly:

# Use context manager
with requests.Session() as session:
    response = session.get("https://api.example.com/data")
    # Session is closed when the block exits

Fix 7: Fix Firewall and Proxy Issues

Check if a firewall is blocking the connection:

# Test TCP connectivity
nc -zv api.example.com 443
# or
telnet api.example.com 443

Configure proxy settings:

proxies = {
    "http": "http://proxy.company.com:8080",
    "https": "http://proxy.company.com:8080",
}

response = requests.get("https://api.example.com/data", proxies=proxies)

Or set environment variables:

export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.company.com"

Bypass proxy for local connections:

response = requests.get("http://localhost:8080/api", proxies={"http": None, "https": None})

Fix 8: Fix Timeout Issues

If the error mentions “timed out”, the server is too slow or unreachable:

# Set explicit timeouts (connect_timeout, read_timeout)
response = requests.get("https://slow-api.example.com/data", timeout=(5, 30))

# 5 seconds to establish the connection
# 30 seconds to receive the response

For very slow APIs:

response = requests.get("https://slow-api.example.com/large-export", timeout=(10, 300))
# 5 minutes read timeout for large responses

With streaming for large responses:

with requests.get("https://example.com/large-file.zip", stream=True, timeout=10) as r:
    r.raise_for_status()
    with open("large-file.zip", "wb") as f:
        for chunk in r.iter_content(chunk_size=8192):
            f.write(chunk)

For deeper timeout tuning and read vs connect distinctions, see Fix: Python requests timeout.

Still Not Working?

Check for rate limiting. Some APIs block you after too many requests:

response = requests.get("https://api.example.com/data")
if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 60))
    time.sleep(retry_after)

Check for IPv6 issues. If the hostname resolves to both IPv4 and IPv6, and IPv6 is not configured properly:

# Force IPv4
import requests
from urllib3.util.connection import allowed_gai_family
import socket

# Monkey-patch to force IPv4
requests.packages.urllib3.util.connection.allowed_gai_family = lambda: socket.AF_INET

Check system resource limits:

# Check file descriptor limit
ulimit -n

# Increase if needed
ulimit -n 65536

Check for a stale keep-alive connection. Long-lived requests.Session objects keep connections in a pool and reuse them. If the server, an intermediate load balancer, or a NAT device closes the connection silently after an idle period (commonly 60–300 seconds), the next request you send on that connection hits a half-closed socket and fails with a connection-reset variant of ConnectionError. The retry usually succeeds because it opens a fresh connection. Either set Connection: close on long-lived sessions, periodically rebuild the session, or set a shorter pool_block timeout. This is by far the most common cause of intermittent “Max retries exceeded” in long-running background workers.

Check for MTU mismatches in containerized environments. If your container is on a Docker bridge network with default 1500-byte MTU but the underlying host network uses a smaller MTU (commonly 1450 on cloud VPNs or overlay networks), large request bodies hang and eventually time out. The connection establishes (small SYN/ACK fits) but the first big POST never completes. Set the container network MTU explicitly to match the host:

# docker-compose.yml
networks:
  default:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: "1450"

Check for DNS resolution that succeeds but returns the wrong IP. Split-horizon DNS, stale entries cached by the JVM-style gethostbyname cache, or a misconfigured /etc/hosts entry can make nslookup show the right answer while Python connects to the wrong IP. Capture what Python actually resolves:

import socket
print(socket.getaddrinfo("api.example.com", 443))

If the returned IP differs from dig output, you have a name resolution mismatch — usually a NSCD or systemd-resolved cache. Restart the resolver.

Debug the exact connection failure:

import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("urllib3").setLevel(logging.DEBUG)

response = requests.get("https://api.example.com/data")
# Shows detailed connection attempts and failures

For Python import errors when installing requests, see Fix: Python ModuleNotFoundError: No module named. For general connection refused errors, see Fix: ERR_CONNECTION_REFUSED localhost.