What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
A requests.exceptions.ReadTimeout means your Python client connected and sent its request, but the server did not send data within the allotted read interval. Set an explicit timeout—usually a separate connect and read budget—then investigate whether the delay comes from the endpoint, network path, or an unsuitable timeout value. Retry only when repeating the request is safe.
What a ReadTimeout means
Requests raises ReadTimeout when the server does not send data during the time allowed for reading. It is different from ConnectTimeout, which occurs while the client is trying to establish a connection. The exception tells you where the request stalled; by itself, it does not establish whether the underlying cause is a slow server, network path, proxy, or client configuration.
Requests does not impose a timeout if you omit the timeout argument. A request can therefore wait indefinitely. Requests’ documentation recommends using a timeout in nearly all production requests.
Set an explicit connect and read timeout
Pass a number to timeout to apply that value to both the connection and read phases, or pass a tuple to set them separately. In timeout=(3.05, 27), the first value is the connect timeout in seconds and the second is the read timeout in seconds. These are example values, not universal settings; choose budgets that fit your network and endpoint.
#1 Best Overall
import requests
url = "https://api.example.com/data"
try:
response = requests.get(url, timeout=(3.05, 27))
response.raise_for_status()
data = response.json()
except requests.exceptions.ReadTimeout:
# The server did not send data within the read interval.
handle_timeout()
except requests.exceptions.ConnectTimeout:
# The connection was not established within the connect interval.
handle_timeout()
except requests.exceptions.Timeout:
# Catch other Requests timeout exceptions if appropriate.
handle_timeout()
Replace handle_timeout() with application-specific handling, such as recording the failure, returning a useful error to a caller, or scheduling a safe retry. If you want a single handler for both connect and read timeouts, catch requests.exceptions.Timeout; the more specific exception handlers must come first because they are subclasses of the broader timeout exception.
Understand what the read timeout does—and does not do
The read timeout is an inactivity threshold: it limits how long the client waits for data between bytes. It is not a wall-clock deadline for the entire request or download. A server that continues to send bytes can keep a streaming response open longer than the configured read timeout without triggering it. If your application needs a hard end-to-end deadline, do not assume that setting timeout alone supplies one; Requests’ connect/read timeout behavior is not a total-duration limit.
Increasing the read value may help when a healthy endpoint legitimately takes longer before sending its next bytes. It will not repair an endpoint that is stuck, a broken network path, or an application that needs a firm overall deadline. A larger inactivity allowance can also make a genuinely stalled operation take longer to fail.
Choose the right fix for the symptom
| Observation | What it points to | Next action |
|---|---|---|
ConnectTimeout |
The connection was not established in time. | Check DNS, TCP/TLS setup, proxy, firewall, and network path; size the connect budget for the environment. |
ReadTimeout |
The client was waiting for server data and the read inactivity interval expired. | Check server response time and logs, then decide whether the endpoint needs optimization or a longer read budget. |
| The request succeeds with a much longer read value but stalls intermittently | The endpoint or path may be slow or variable; the longer value changes when the client gives up, not the cause. | Measure recurring delays and investigate server and network behavior before making a longer timeout permanent. |
| An HTTP 4xx response arrives | The server returned an application-level client error; this is not a timeout. | Inspect the response and correct the request, credentials, permissions, or other relevant input. |
Call raise_for_status() after receiving a response when you want unsuccessful HTTP status codes to raise an exception. A 4xx response is different from a timeout: the server responded, so simply increasing the timeout is not the remedy.
Diagnose the failure before changing production settings
- Record what failed. Capture the exception class, URL, HTTP method, configured timeout values, elapsed time, and whether the request received any response bytes. Avoid logging credentials, authorization headers, or sensitive query parameters.
- Separate connection from reading. Use a tuple timeout so the connection budget and read inactivity budget can be considered independently. A connection delay calls for different investigation from a server that accepted the request but did not send data promptly.
- Reproduce from the same environment. Test a minimal request from the same host, proxy configuration, and network path as the failing program. A request from a developer laptop may not reproduce a problem in a container or production network.
- Check the path and the endpoint. Review DNS resolution, proxy settings, TLS setup, firewall behavior, and server-side logs. Do not assume the Python client is at fault simply because it is where the exception appears.
- Decide whether the operation is slow or stuck. If the endpoint is healthy but takes longer to produce data, a read budget suited to that latency may be appropriate. If it stops responding, ask the service owner to investigate or change the endpoint rather than masking the failure with an arbitrarily large timeout.
- Add retries only for transient failures and safe operations. Use bounded retries with backoff where appropriate, and ensure the request can safely be repeated.
Use bounded retries when repeating the request is safe
Requests’ HTTPAdapter defaults max_retries to zero. For controlled retries, mount an adapter configured with urllib3’s Retry. The example below retries selected transient status codes and connection/read failures, with a bounded total and backoff. Its values are illustrative; they are not a recommended fit for every service.
from requests import Session
from requests.adapters import HTTPAdapter
from urllib3.util import Retry
retry = Retry(
total=3,
connect=3,
read=3,
backoff_factor=0.5,
status_forcelist=(429, 500, 502, 503, 504),
allowed_methods=frozenset({"GET", "HEAD", "OPTIONS"}),
)
session = Session()
session.mount("https://", HTTPAdapter(max_retries=retry))
response = session.get(
"https://api.example.com/data",
timeout=(3.05, 27),
)
response.raise_for_status()
Retries can multiply the time an application spends waiting: each attempt may use its own timeout, and backoff adds delay between attempts. Account for that when deciding how long a caller or job is allowed to wait. Confirm how the API handles rate limits and transient errors, and keep retry behavior bounded.
Do not blindly retry writes
A timeout does not necessarily tell you whether the server completed an operation before the response was lost. Repeating a non-idempotent write—such as creating a new payment or record—could perform the action twice. Inspect the API’s semantics and use an idempotency mechanism where the service supports one; otherwise, determine the outcome before repeating the write. The example’s method allowlist limits retries to GET, HEAD, and OPTIONS, but even apparently safe operations should be evaluated against the particular service.
Use a Session for a consistent request policy
A Session lets you reuse a configured adapter across requests, as in the retry example. That is useful when multiple calls should share retry behavior. It does not mean you should omit timeout: supply an explicit timeout on requests so each operation has a deliberate connect and read budget. If different endpoints have different latency profiles, set appropriate values at the call site rather than assuming one value suits all of them.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteCommon ReadTimeout causes and fixes
- The server is slow to produce a response: inspect server timing and logs; optimize the endpoint or select a read inactivity threshold that reflects its expected behavior.
- The server stopped sending data: treat the timeout as a signal to investigate the service or path. A longer interval only delays the failure decision.
- The request runs through a proxy or restricted network: reproduce using the same proxy and network configuration, then check proxy, firewall, DNS, and TLS behavior.
- The timeout was omitted: add an explicit timeout; without one, Requests does not time out by default.
- The timeout values were confused: with a tuple, the first number is connect and the second read. A read timeout is not a maximum total download duration.
- The code retries unsafely: restrict retries to operations that can be repeated safely, use bounded attempts and backoff, and inspect API idempotency behavior for writes.
- The response is an HTTP error rather than a timeout: inspect the status and response body, then use
raise_for_status()if your code should raise for unsuccessful statuses. Correct the request or application condition instead of extending a timeout.
Performance, reliability, and cost of waiting
Timeouts are a reliability boundary, not a speed improvement: a shorter read timeout makes stalled calls fail sooner, while a longer one tolerates more inactivity but can occupy a worker for longer. Neither setting makes a slow server send data faster. Bounded retries can smooth over transient faults, but they also add load and latency, especially if many clients retry together. Choose timeout and retry budgets in the context of the endpoint’s expected response behavior and the amount of time your application can spend waiting.
For a recurring problem, correlate client-side timing with server logs and network-path observations. Track which phase timed out and how often, rather than repeatedly increasing the threshold without evidence. That distinction helps determine whether to adjust a client budget, repair connectivity, or improve the endpoint.
Or skip the browser setup
If the task behind your request is to capture a website screenshot, you can call ScreenshotNeo’s screenshot API instead of setting up and maintaining your own browser capture flow. It is still an HTTP request, so use an explicit Requests timeout and handle failures in your application; it does not eliminate the need to diagnose a genuine network or read timeout. See the ScreenshotNeo API documentation.
Quick Recap
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)
ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, with X-Page-Verdict and X-Billed response headers indicating the result. It also provides an MCP server for AI agents, including Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Learn more at ScreenshotNeo, or sign up free for 1,000 screenshots a month with no card.
Recommended Free Tools
Python Requests ReadTimeout checklist
- Set
timeoutexplicitly for production calls. - Use a tuple when you need separate connect and read budgets.
- Remember that read timeout measures inactivity between bytes, not total request duration.
- Identify whether the failure is a connection timeout, read timeout, or HTTP error.
- Check the endpoint and the same network path before blaming the client.
- Retry only bounded, repeatable operations and account for the added wait.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
