To retry failed calls in Python requests, create a urllib3.util.Retry with total, backoff_factor and status_forcelist, wrap it in an HTTPAdapter(max_retries=retry), mount the adapter on a requests.Session, and pass a timeout on every call. requests then retries errors and listed status codes with growing waits.
We ran every snippet below on 20 November 2026 with Python 3.12.10, requests 2.34.2 and urllib3 2.8.0, through a QuanticData Residential Basic session in the US, against httpbin.org, a public test service that returns the status codes and delays you ask for. The waits are measured from urllib3's own debug log.
The retry setup, step by step
- Import
HTTPAdapterfrom requests andRetryfrom urllib3. - Describe the policy: how many retries, which status codes, how long to wait.
- Mount it on a Session for
https://andhttp://. - Call with a timeout. Retries only start once something fails; a timeout makes a hung call fail.
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
PROXY = "http://USER-type-residential-country-us-session-r01-lifetime-30:PASS@residentialboson.quanticdata.io:10000"
retry = Retry(
total=4, # up to 4 retries, 5 requests in all
backoff_factor=1, # waits grow: 0, 2, 4, 8 s
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["GET", "POST"],
respect_retry_after_header=True,
)
s = requests.Session()
s.proxies = {"http": PROXY, "https": PROXY}
s.mount("https://", HTTPAdapter(max_retries=retry))
s.mount("http://", HTTPAdapter(max_retries=retry))
r = s.get("https://httpbin.org/status/503", timeout=(5, 20))
httpbin.org/status/503 answers 503 every time, so the policy runs to the end. Five requests went out, then requests raised:
requests.exceptions.RetryError: HTTPSConnectionPool(host='httpbin.org', port=443):
Max retries exceeded with url: /status/503 (Caused by ResponseError('too many 503 error responses'))
What backoff_factor really waits
This is where most guides guess. We read the timestamps of each attempt from the urllib3 log:
| Attempt | Wait before it (backoff_factor=1) |
|---|---|
| First request | none |
| Retry 1 | 0 s, it went out at once |
| Retry 2 | 2 s |
| Retry 3 | 4 s |
| Retry 4 | 8 s |
| RetryError raised | 16.8 s after the start |
So in urllib3 2.8 the wait is backoff_factor * 2 ** (n - 1) from the second retry on, and zero before the first one. With backoff_factor=0.5 the waits halve. Two more knobs: backoff_max caps the wait (120 s by default) and backoff_jitter adds a random part so many workers do not retry in step.
Retry-After and 429 responses
When a server answers 429 or 503 with a Retry-After header, Retry waits that long instead of its own backoff, because respect_retry_after_header is on by default. We checked it against a small local server that answered 429 with Retry-After: 3 twice, then 200:
Retry-After: 200 ok after 3 hits, gaps between hits [3.0, 3.0] s, total 6.1s
The backoff in that test was 0.1, so the 3-second gaps came from the header. A 429 means you sent too much; slow down and honour Retry-After. More on that in 429 Too Many Requests.
Return the last response instead of raising
By default, running out of retries raises RetryError. With raise_on_status=False, requests hands back the last response, and you decide:
retry = Retry(total=2, backoff_factor=0.5, status_forcelist=[503], raise_on_status=False)
s.mount("https://", HTTPAdapter(max_retries=retry))
r = s.get("https://httpbin.org/status/503", timeout=(5, 20))
print(r.status_code) # 503, after 2.9 s
Python requests timeout: connect and read
requests has no default timeout: without one, a call can wait forever. The timeout parameter is in seconds and takes one number for both phases or a tuple (connect, read). Our runs:
| Call | Result |
|---|---|
timeout=(5, 3) on a page that waits 10 s | ReadTimeout after 3.9 s |
timeout=(5, 10) on a page that waits 2 s | 200 |
timeout=(2, 5) on an address that never answers | ConnectTimeout after 2.0 s |
Retry with read=2, timeout=(5, 3), page that waits 10 s | ConnectionError (max retries) after 17.8 s |
- The read timeout is not a total time limit. It is the longest pause between bytes. A slow page that keeps sending can run longer.
- Through a proxy, the connect timeout covers the connection to the gateway, and the read timeout covers the wait for the site's answer through it.
- Catch
requests.exceptions.Timeoutto handle both kinds;ConnectTimeoutandReadTimeoutare its subclasses. - Retry on timeout with
connect=andread=in Retry, as in the last row. A read retry resends the request, so keep it to calls that are safe to repeat.
Retrying with tenacity
Retry in the adapter only sees HTTP. To retry on your own conditions (an empty result, a parse error, a proxy error), wrap the function with tenacity:
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
@retry(stop=stop_after_attempt(4),
wait=wait_exponential(multiplier=1, min=1, max=10),
retry=retry_if_exception_type((requests.ConnectionError, requests.Timeout, requests.HTTPError)),
reraise=True)
def fetch(url):
r = requests.get(url, proxies={"http": PROXY, "https": PROXY}, timeout=(5, 15))
r.raise_for_status()
return r
On httpbin.org/status/500 it gave up after 4 attempts and 10.5 s and re-raised the HTTPError; on ipinfo.io the first attempt returned 200, from Independence, Kansas.
What to retry, and when to stop
Retries are for transient trouble: a timeout, a dropped connection, a 502, 503 or 504 from a server that is briefly overloaded. They should wait longer each time, stop after a few attempts, and honour Retry-After. Some answers are not transient and should not be retried at all:
- 403 Forbidden: the site refuses the request. Repeating it does not change that; stop and check whether you may access the page at all.
- 429 Too Many Requests: you are going too fast. Wait as long as Retry-After says, lower your rate, and if the site keeps answering 429, stop.
- 400, 401, 404: something is wrong in the request itself. Fix it rather than send it again.
The tenacity version above can make that distinction with a small predicate instead of retrying every HTTPError:
from tenacity import retry_if_exception
def transient(e):
if isinstance(e, (requests.ConnectionError, requests.Timeout)):
return True
return isinstance(e, requests.HTTPError) and e.response is not None \
and e.response.status_code >= 500
@retry(stop=stop_after_attempt(4), wait=wait_exponential(multiplier=1, min=1, max=10),
retry=retry_if_exception(transient), reraise=True)
def fetch(url): ...
With that predicate, httpbin.org/status/500 was tried 4 times before the error was raised, while /status/403 and /status/429 were tried once each and raised straight away. In the adapter version, the same choice is made by what you list in status_forcelist.
Retry also covers a proxy that cannot be reached: when we pointed requests at a closed local port as proxy with Retry(total=2), it retried twice, then raised ProxyError('Unable to connect to proxy'). A 407 is a wrong username or password and will not get better with retries; see requests.exceptions.ProxyError. The proxy setup itself is in how to use a proxy with Python requests. Plans: residential proxies, mobile proxies, and a Residential Basic free trial.


