requests runtime, network, API python requests network timeout
Kenji Tanaka Full-Stack Developer

requests.exceptions.Timeout: HTTPSConnectionPool

Encountering a requests.exceptions.Timeout means the requests library exceeded its configured waiting time for a server response; this guide explains how to fix it.

What This Error Means

The requests.exceptions.Timeout: HTTPSConnectionPool error indicates that your Python application, using the requests library, failed to receive a response from a remote server within a specified timeframe. It's a client-side error, specifically an requests.exceptions.Timeout subclass, and it means your application "gave up" waiting. The HTTPSConnectionPool part specifies that the timeout occurred during an HTTPS request, which is common for API interactions and web scraping.

Crucially, this error doesn't necessarily mean the server is down or that your request never reached it. It simply means that your client didn't hear back within the duration it was prepared to wait. This could be because the server is too slow, the network is congested, or your timeout setting is simply too aggressive for the operation you're performing.

Why It Happens

At its core, a timeout happens because the expected duration of a network operation (like establishing a connection or receiving data) was exceeded. When you make an HTTP request using requests, there are typically two phases where a timeout can occur:

  1. Connection Timeout (connect): This is the time limit for establishing a connection to the remote server. It includes the DNS lookup, TCP handshake, and SSL handshake. If the client can't even "talk" to the server within this period, a timeout occurs.
  2. Read Timeout (read): Once a connection is established, this is the time limit for the client to wait for the server to send any data back. If the server accepts the connection but then takes too long to respond with the first byte of data (or any subsequent bytes if streaming), a read timeout will be triggered.

If neither a connect nor read timeout is explicitly set, requests will wait indefinitely, which is rarely desirable in production systems. In my experience, forgetting to set a timeout is a common oversight that can lead to hanging processes.

Common Causes

Identifying the root cause of a requests.exceptions.Timeout can involve looking at several layers of your system and the remote service. Here are the most common scenarios I've encountered:

  • Server Overload or Slow Response: The target API or web server is genuinely struggling to handle the request. This might be due to high traffic, inefficient database queries, or resource contention on the server. I've seen this in production when an upstream service suddenly became popular or had a bug introduced.
  • Network Latency or Instability: The physical network path between your client and the server is experiencing delays. This could be due to internet congestion, routing issues, or high packet loss.
  • Firewall or Security Group Restrictions: An intermediary firewall (on your machine, network, or the server's cloud provider) might be silently dropping packets, causing the connection attempt to hang until it times out. This is a common issue, especially when deploying to new environments.
  • Incorrect DNS Resolution: Your application might be trying to connect to the wrong IP address because of stale DNS caches or misconfigured DNS servers, leading to attempts to connect to a non-existent host.
  • Insufficient Timeout Configuration: The timeout value set in your requests call is simply too low for the expected operation. Some API calls are inherently slow (e.g., generating large reports, complex computations), and a default or low timeout won't suffice.
  • Proxy Server Issues: If your application uses a proxy, the proxy itself might be slow, misconfigured, or experiencing network issues, preventing your requests from reaching their destination in time.
  • Large Data Transfers: For very large uploads or downloads, if the read timeout is not configured appropriately or the network is slow, it can easily trigger this error.

Step-by-Step Fix

Troubleshooting this error requires a methodical approach. Follow these steps to diagnose and resolve the issue.

1. Reproduce the Issue Consistently

First, try to reproduce the timeout error reliably. Is it happening every time? Only under certain conditions (e.g., specific API endpoints, peak hours, large payloads)? Understanding its frequency and context will help narrow down the cause.

2. Inspect Your requests Timeout Configuration

Review the code where you make the requests call. Are you specifying a timeout parameter?

import requests

try:
    response = requests.get('https://api.example.com/data', timeout=5) # Is there a timeout?
    response.raise_for_status()
    print(response.json())
except requests.exceptions.Timeout:
    print("The request timed out!")
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

If no timeout is specified, requests will wait indefinitely, so the Timeout exception will never be raised directly in that case, but the process might hang. Always specify a timeout in production code.

3. Incrementally Increase the Timeout (Cautiously)

If you have a timeout set, try increasing it. Remember, timeout can be a single float (for both connect and read) or a tuple (connect_timeout, read_timeout). Start with a reasonable value and increase it gradually.

import requests

# Try a higher timeout, e.g., 10 seconds total
# Or specify connect and read separately
# requests.get(url, timeout=(3, 7)) # 3s for connect, 7s for read
try:
    response = requests.get('https://api.example.com/data', timeout=10)
    response.raise_for_status()
    print(response.json())
except requests.exceptions.Timeout:
    print("The request still timed out after increasing the timeout!")
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

If increasing the timeout fixes the issue, it suggests the server is slow or the operation is inherently long-running. You'll need to decide if the new timeout is acceptable or if the server's performance needs optimization. Avoid setting excessively long timeouts, as this can mask underlying problems and tie up resources.

4. Perform Network Diagnostics

If increasing the timeout doesn't help or if the timeout is occurring on connection attempts, investigate the network path:

  • ping: Check basic connectivity and latency to the target host.
    bash ping api.example.com
  • traceroute (Linux/macOS) or tracert (Windows): Trace the network route to identify where delays or packet drops might be occurring.
    bash traceroute api.example.com
  • curl: Use curl with verbose output and a short timeout to see if the issue is specific to requests or a general network problem.
    bash curl -v --connect-timeout 5 https://api.example.com/data
    I often reach for curl -v first when I suspect network issues, as it gives excellent low-level details.

5. Check Server Health and API Performance

If you manage the API server, check its logs, resource utilization (CPU, memory, disk I/O, network I/O), and specific endpoint performance metrics. If it's a third-party API, check their status page or documentation for known issues.

6. Verify Firewall and Proxy Settings

  • Local Firewall: Ensure your operating system's firewall isn't blocking outgoing connections on port 443 (HTTPS).
  • Network Firewalls/Security Groups: If running in a cloud environment, verify that your instances' security groups or network ACLs allow outbound HTTPS traffic to the target. I've spent more time than I'd like admitting debugging security group issues.
  • Proxy Configuration: If you're using a proxy, ensure its settings are correct and that the proxy itself isn't a bottleneck or experiencing issues.

7. Confirm DNS Resolution

Ensure your system is resolving the target hostname correctly.

dig api.example.com
# or
nslookup api.example.com

Look for the correct IP address and reasonable response times.

8. Implement Robust Retry Logic

For transient network issues or temporary server slowness, implementing retry logic is crucial. The requests library itself can be configured with a Session and Retry object, or you can use a library like tenacity.

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

# Configure retries for specific HTTP statuses and for timeouts
retries = Retry(
    total=5,
    backoff_factor=1,
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["HEAD", "GET", "POST", "PUT", "DELETE", "OPTIONS"],
    raise_on_status=False, # Don't raise for HTTP status errors immediately
)

# Also handle connection errors (which include timeouts)
retries.respect_retry_after_header = True # Respect Retry-After header
retries.connect = 5 # Number of retries for connection errors

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

try:
    # Use the session for your requests, with its own timeout
    response = session.get('https://api.example.com/data', timeout=(5, 10)) # Connect 5s, Read 10s
    response.raise_for_status()
    print(response.json())
except requests.exceptions.Timeout:
    print("Request timed out even after retries!")
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

Retries are an essential pattern for building resilient systems, especially when dealing with external APIs.

Code Examples

Here are concise, copy-paste ready examples showcasing various timeout and retry strategies.

Basic GET with Timeout

import requests

try:
    # Set a 5-second timeout for both connection and read
    response = requests.get('https://httpbin.org/delay/6', timeout=5)
    response.raise_for_status()
    print("Success:", response.json())
except requests.exceptions.Timeout:
    print("Error: The request timed out after 5 seconds.")
except requests.exceptions.RequestException as e:
    print(f"An unexpected request error occurred: {e}")

Separate Connect and Read Timeouts

import requests

try:
    # Set a 2-second connect timeout and a 10-second read timeout
    response = requests.get('https://httpbin.org/delay/11', timeout=(2, 10))
    response.raise_for_status()
    print("Success:", response.json())
except requests.exceptions.ConnectTimeout:
    print("Error: Connection to the server timed out after 2 seconds.")
except requests.exceptions.ReadTimeout:
    print("Error: No data received from the server within 10 seconds after connecting.")
except requests.exceptions.Timeout:
    print("Error: A generic timeout occurred (should not happen with specific timeouts handled).")
except requests.exceptions.RequestException as e:
    print(f"An unexpected request error occurred: {e}")

Using requests Session with Retry Logic

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

def make_retriable_session(total_retries=3, backoff_factor=0.5):
    """
    Creates a requests Session with retry logic for specific HTTP statuses and connection errors.
    """
    retries = Retry(
        total=total_retries,
        read=total_retries,
        connect=total_retries,
        backoff_factor=backoff_factor,
        status_forcelist=[500, 502, 503, 504],
        # Also retry on specific connection errors, which includes timeouts
        # For simplicity, connect=total_retries covers the timeout scenario here
    )
    adapter = HTTPAdapter(max_retries=retries)
    session = requests.Session()
    session.mount("http://", adapter)
    session.mount("https://", adapter)
    return session

session = make_retriable_session(total_retries=4, backoff_factor=1)

try:
    # Use the session for the request, with an overall timeout for each attempt
    # The retries apply to the *attempts*, each attempt still has its own timeout
    response = session.get('https://httpbin.org/status/503', timeout=(3, 7))
    response.raise_for_status()
    print("Success:", response.text)
except requests.exceptions.Timeout:
    print("Error: Request timed out even after multiple retries.")
except requests.exceptions.RequestException as e:
    print(f"Error after retries: {e}")

Using tenacity for Advanced Retries

tenacity provides more sophisticated retry decorators, including stop conditions and wait strategies.

import requests
from tenacity import retry, stop_after_attempt, wait_exponential, RetryError, TryAgain, wait_fixed

@retry(
    stop=stop_after_attempt(5),
    wait=wait_exponential(multiplier=1, min=2, max=10), # 2s, 4s, 8s, 10s...
    retry=(
        # Retry on any requests.exceptions.Timeout or specific HTTP statuses
        requests.exceptions.Timeout |
        requests.exceptions.ConnectionError |
        requests.exceptions.HTTPError
    ),
    reraise=True # Re-raise the last exception if all retries fail
)
def fetch_data_with_retries(url, timeout=(3, 7)):
    """
    Fetches data from a URL with robust retry logic using tenacity.
    Raises RequestException if all retries fail.
    """
    print(f"Attempting to fetch {url}...")
    response = requests.get(url, timeout=timeout)
    response.raise_for_status() # Raises HTTPError for bad status codes
    return response.json()

try:
    data = fetch_data_with_retries('https://httpbin.org/delay/8') # This will timeout on first attempt, then retry
    print("Success after retries:", data)
except RetryError as e:
    print(f"All retry attempts failed. Last error: {e.last_attempt.exception()}")
except requests.exceptions.RequestException as e:
    print(f"Final error after all retries: {e}")

Environment-Specific Notes

The source of timeouts can vary significantly depending on where your application is running.

Local Development

  • Firewall: Your operating system's firewall (e.g., Windows Defender, ufw on Linux, macOS firewall) is a frequent culprit. Check logs or temporarily disable it for testing.
  • VPN/Proxy: If you're using a corporate VPN or a local proxy, it might be interfering with network traffic.
  • Misconfigured Hosts File: Sometimes, an incorrect entry in your /etc/hosts file (or C:\Windows\System32\drivers\etc\hosts) can point a domain to the wrong IP, causing connection timeouts.
  • Network Hardware: Local Wi-Fi issues or a faulty router can also introduce intermittent timeouts.

Cloud Environments (AWS, GCP, Azure)

  • Security Groups/Network ACLs: This is the #1 suspect in cloud environments. Ensure the security group attached to your instance allows outbound connections to port 443 (HTTPS) to the internet or specific IP ranges. Similarly, check inbound rules on the target server.
  • VPC Routing/Subnets: Verify that your instance is in a public subnet with a NAT Gateway/Instance if it needs to reach the internet, or that VPC Peering/PrivateLink is correctly configured for private API access.
  • Load Balancers: If your application talks to an internal load balancer (or sits behind one), check the load balancer's health checks and target group configuration.
  • Cloud Firewalls: Cloud providers also have more granular firewall services (e.g., AWS WAF, GCP Firewall Rules) that might be blocking traffic.
  • Resource Limits: The instance itself might be under-resourced (CPU/memory starved), causing your application to struggle with network I/O.

Docker/Containerized Environments

  • DNS Resolution within Docker: Containers often use Docker's internal DNS resolver. If this is misconfigured or has issues, containers might fail to resolve external hostnames. Check /etc/resolv.conf inside the container. I've had to explicitly set dns in docker-compose.yml to public DNS servers at times.
  • Docker Network Configuration: Ensure your container has network access. If it's part of a custom Docker network, verify the network settings and connectivity to external services.
  • Resource Limits: Like cloud instances, containers with low CPU or memory limits can struggle to process requests and responses in time.
  • Proxy Settings: If your container needs to use a proxy, ensure environment variables like HTTP_PROXY, HTTPS_PROXY, and NO_PROXY are correctly set within the container.

Frequently Asked Questions

Q: What's the difference between connect and read timeouts?
A: The connect timeout is the maximum time allowed for your client to establish a TCP connection with the remote server, including DNS lookup and SSL handshake. The read timeout is the maximum time allowed for the server to send any data back after the connection has been established. If you specify a single value for timeout, it applies to both phases.

Q: Should I just set a very high timeout value to avoid this error?
A: While increasing the timeout can resolve the error, setting an excessively high timeout (e.g., several minutes) is generally discouraged. It can mask underlying performance issues with the server or network, tie up client-side resources for too long, and degrade the responsiveness of your application. It's better to find a balance between stability and responsiveness.

Q: Can this timeout error be caused by my client-side network issues?
A: Absolutely. Network congestion, slow Wi-Fi, faulty network cables, or even a local firewall blocking outbound connections can all lead to requests.exceptions.Timeout. Always consider your local network environment when troubleshooting.

Q: How do retries help with timeouts?
A: Retries make your application more resilient to transient issues. If a timeout occurs due to temporary network instability or a momentary server overload, a subsequent retry (after a short delay, often with exponential backoff) might succeed. This prevents your application from failing unnecessarily due to fleeting problems.

Q: Is it safe to catch requests.exceptions.Timeout?
A: Yes, it is explicitly designed to be caught. Catching this specific exception allows your application to handle situations where a remote service is slow or unresponsive gracefully, rather than crashing. You can log the error, implement fallback logic, or retry the request.