Documentation Python quickstart Blog Free tools Enterprise solutions hello@quanticdata.ioLog in

Python requests retry: Retry, backoff_factor and timeouts, with measured waits

A Python requests Session with an HTTPAdapter and a urllib3 Retry of four retries and backoff_factor 1 retries a 503 response; the card shows the waits we measured between attempts, none before the first retry, then 2, 4 and 8 seconds, and a RetryError after 16.8 seconds.
A Python requests Session with an HTTPAdapter and a urllib3 Retry of four retries and backoff_factor 1 retries a 503 response; the card shows the waits we measured between attempts, none before the first retry, then 2, 4 and 8 seconds, and a RetryError after 16.8 seconds.

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

  1. Import HTTPAdapter from requests and Retry from urllib3.
  2. Describe the policy: how many retries, which status codes, how long to wait.
  3. Mount it on a Session for https:// and http://.
  4. 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:

AttemptWait before it (backoff_factor=1)
First requestnone
Retry 10 s, it went out at once
Retry 22 s
Retry 34 s
Retry 48 s
RetryError raised16.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:

CallResult
timeout=(5, 3) on a page that waits 10 sReadTimeout after 3.9 s
timeout=(5, 10) on a page that waits 2 s200
timeout=(2, 5) on an address that never answersConnectTimeout after 2.0 s
Retry with read=2, timeout=(5, 3), page that waits 10 sConnectionError (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.Timeout to handle both kinds; ConnectTimeout and ReadTimeout are its subclasses.
  • Retry on timeout with connect= and read= 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.

Sources & further reading

FAQ

Quick answers on python requests retry.

Something else? Ask us

How do I retry requests in Python?

Create Retry(total=4, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504]) from urllib3, mount HTTPAdapter(max_retries=retry) on a requests.Session for https:// and http://, and call through the session with a timeout.

What does backoff_factor do in requests Retry?

It sets the wait between retries. In our test with urllib3 2.8 and backoff_factor=1, the first retry went out at once and the next ones waited 2, 4 and 8 seconds. backoff_max caps the wait and backoff_jitter adds randomness.

What is the default timeout in Python requests?

There is none: without timeout=, a request can wait forever. Pass a number of seconds, or a tuple such as (5, 30) for the connect and read phases.

Is the requests timeout in seconds or milliseconds?

Seconds. timeout=3 is three seconds; floats such as 0.5 work too. In our test timeout=(5, 3) raised ReadTimeout after 3.9 s on a page that waits 10 s.

Does requests Retry respect the Retry-After header?

Yes, by default, for 413, 429 and 503 responses. Our local server sent 429 with Retry-After: 3 twice; requests waited 3.0 s each time and got 200 on the third request.

Should I retry a 403 or a 429?

Not a 403: the site refuses the request, and repeating it does not change that. A 429 means slow down: wait as long as Retry-After says and lower your rate, and stop if it continues. In our test, a predicate that retries only timeouts, connection errors and 5xx tried a 500 four times and a 403 or 429 once.

Proxies for requests and urllib3 Retry

Residential and mobile proxies with country, rotation and session settings in the username, ready for requests, urllib3 Retry and tenacity.

Collectors with Python examples

Related reading