364

The Python requests module is simple and elegant but one thing bugs me. It is possible to get a requests.exception.ConnectionError with a message like:

Max retries exceeded with url: ...

This implies that requests can attempt to access the data several times. But there is not a single mention of this possibility anywhere in the docs. Looking at the source code I didn't find any place where I could alter the default (presumably 0) value.

So is it possible to somehow set the maximum number of retries for requests?

4
  • 12
    Any update on this with requests at 2.x? Would love a requests.get(url, max_retries=num_max_retries)) implementation.
    – paragbaxi
    Commented Jan 27, 2014 at 1:33
  • 27
    @paragbaxi: and even better a requests.get(url, max_retries=num_max_retries, dely_between_retries=3))
    – WoJ
    Commented Feb 27, 2015 at 21:26
  • 6
    @WoJ I took your examples and made it reality ;) in just.get and just.post in github.com/kootenpv/just Commented Dec 5, 2016 at 21:47
  • 7
    Useful article about retries with Requests: peterbe.com/plog/best-practice-with-retries-with-requests
    – Gokul
    Commented Apr 26, 2019 at 8:07

6 Answers 6

499

This will not only change the max_retries but also enable a backoff strategy which makes requests to all http:// addresses sleep for a period of time before retrying (to a total of 5 times):

import requests

from requests.adapters import HTTPAdapter, Retry

s = requests.Session()

retries = Retry(total=5,
                backoff_factor=0.1,
                status_forcelist=[ 500, 502, 503, 504 ])

s.mount('http://', HTTPAdapter(max_retries=retries))

s.get('http://httpstat.us/500')

As per documentation for Retry: if the backoff_factor is 0.1, then sleep() will sleep for [0.05s, 0.1s, 0.2s, 0.4s, ...] between retries. It will also force a retry if the status code returned is 500, 502, 503 or 504.

Various other options to Retry allow for more granular control:

  • total – Total number of retries to allow.
  • connect – How many connection-related errors to retry on.
  • read – How many times to retry on read errors.
  • redirect – How many redirects to perform.
  • method_whitelist – Set of uppercased HTTP method verbs that we should retry on.
  • status_forcelist – A set of HTTP status codes that we should force a retry on.
  • backoff_factor – A backoff factor to apply between attempts.
  • raise_on_redirect – Whether, if the number of redirects is exhausted, to raise a MaxRetryError, or to return a response with a response code in the 3xx range.
  • raise_on_status – Similar meaning to raise_on_redirect: whether we should raise an exception, or return a response, if status falls in status_forcelist range and retries have been exhausted.

NB: raise_on_status is relatively new, and has not made it into a release of urllib3 or requests yet. The raise_on_status keyword argument appears to have made it into the standard library at most in python version 3.6.

To make requests retry on specific HTTP status codes, use status_forcelist. For example, status_forcelist=[503] will retry on status code 503 (service unavailable).

By default, the retry only fires for these conditions:

  • Could not get a connection from the pool.
  • TimeoutError
  • HTTPException raised (from http.client in Python 3 else httplib). This seems to be low-level HTTP exceptions, like URL or protocol not formed correctly.
  • SocketError
  • ProtocolError

Notice that these are all exceptions that prevent a regular HTTP response from being received. If any regular response is generated, no retry is done. Without using the status_forcelist, even a response with status 500 will not be retried.

To make it behave in a manner which is more intuitive for working with a remote API or web server, I would use the above code snippet, which forces retries on statuses 500, 502, 503 and 504, all of which are not uncommon on the web and (possibly) recoverable given a big enough backoff period.

15
  • 2
    I am trying to implement your logic, but I dont know if it is working because the log just show one request even the res status is 503. How I can know if the retry is working? See the code: pastebin.com/rty4bKTw Commented Feb 24, 2016 at 20:55
  • 1
    The attached code works as expected. The trick is the status_forcelist parameter. This tells the urllib3 package to retry specific status codes. Code: pastebin.com/k2bFbH7Z
    – datashaman
    Commented Feb 25, 2016 at 16:54
  • 1
    urllib3 does not (and should not) think that status 503 is an exception (by default).
    – datashaman
    Commented Feb 25, 2016 at 17:15
  • 1
    @Connor no, the adapter is attached to the session.
    – datashaman
    Commented Aug 30, 2018 at 8:10
  • 2
    urlib3.Retry is no longer part of requests. this have to imported directly. Suggested edit Commented Apr 16, 2019 at 10:25
237

It is the underlying urllib3 library that does the retrying. To set a different maximum retry count, use alternative transport adapters:

from requests.adapters import HTTPAdapter

s = requests.Session()
s.mount('http://stackoverflow.com', HTTPAdapter(max_retries=5))

The max_retries argument takes an integer or a Retry() object; the latter gives you fine-grained control over what kinds of failures are retried (an integer value is turned into a Retry() instance which only handles connection failures; errors after a connection is made are by default not handled as these could lead to side-effects).


Old answer, predating the release of requests 1.2.1:

The requests library doesn't really make this configurable, nor does it intend to (see this pull request). Currently (requests 1.1), the retries count is set to 0. If you really want to set it to a higher value, you'll have to set this globally:

import requests

requests.adapters.DEFAULT_RETRIES = 5

This constant is not documented; use it at your own peril as future releases could change how this is handled.

Update: and this did change; in version 1.2.1 the option to set the max_retries parameter on the HTTPAdapter() class was added, so that now you have to use alternative transport adapters, see above. The monkey-patch approach no longer works, unless you also patch the HTTPAdapter.__init__() defaults (very much not recommended).

3
  • 1
    @user136036: yes, adapters are looked up by longest prefix match; if you want this to apply to all urls then http:// and https:// are the minimal prefixes to use, see the documentation the answer links to. Commented Apr 26, 2015 at 21:00
  • 4
    Note that HTTPAdapter(max_retries=5) will only work for certain scenario. From requests doc, Note, this applies only to failed DNS lookups, socket connections and connection timeouts, never to requests where data has made it to the server. By default, Requests does not retry failed connections. To force retry for any status codes, see @datashaman's answer below.
    – Steven Xu
    Commented Sep 26, 2017 at 3:45
  • @StevenXu: yes, you can configure Retry() to alter what failure scenarios are retried. Commented Sep 26, 2017 at 6:50
68

Be careful, Martijn Pieters's answer isn't suitable for version 1.2.1+. You can't set it globally without patching the library.

You can do this instead:

import requests
from requests.adapters import HTTPAdapter

s = requests.Session()
s.mount('http://www.github.com', HTTPAdapter(max_retries=5))
s.mount('https://www.github.com', HTTPAdapter(max_retries=5))
3
  • 25
    Nice solution but note that there is no delay between retries. If you want to sleep between attempts, you will need to roll your own.
    – nofinator
    Commented Oct 2, 2013 at 20:08
  • 3
    you can add timeout as well findwork.dev/blog/… see this Commented Dec 21, 2020 at 18:41
  • @DJ_Stuffy_K great article!
    – Hohenheim
    Commented Mar 30, 2021 at 3:26
39

After struggling a bit with some of the answers here, I found a library called backoff that worked better for my situation. A basic example:

import backoff

@backoff.on_exception(
    backoff.expo,
    requests.exceptions.RequestException,
    max_tries=5,
    giveup=lambda e: e.response is not None and e.response.status_code < 500
)
def publish(self, data):
    r = requests.post(url, timeout=10, json=data)
    r.raise_for_status()

I'd still recommend giving the library's native functionality a shot, but if you run into any problems or need broader control, backoff is an option.

2
  • 4
    great library, thank you! I needed this functionality for something else than requests, so this works perfectly! Commented Nov 2, 2018 at 0:31
  • This lib is a much cleaner solution Commented Aug 3 at 11:58
17

You can use the requests library to accomplish all in one go. The following code will retry 3 times if you receive 429,500,502,503 or 504 status code, each time with a longer delay set through "backoff_factor". See https://findwork.dev/blog/advanced-usage-python-requests-timeouts-retries-hooks/ for a nice tutorial.

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

retry_strategy = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[429, 500, 502, 503, 504],
    method_whitelist=["HEAD", "GET", "OPTIONS"]
)
adapter = HTTPAdapter(max_retries=retry_strategy)
http = requests.Session()
http.mount("https://", adapter)
http.mount("http://", adapter)

response = http.get("https://en.wikipedia.org/w/api.php")
3
  • From my tests, you don't need to include 429 on status_forcelist because it is already automatically retried. Commented Oct 30, 2022 at 22:19
  • 2
    @PabloCastellano only if you don’t override status_forcelist.
    – bfontaine
    Commented Nov 20, 2023 at 15:06
  • 2
    In case someone wants to try this, method_whitelist has been deprecated in favor of allowed_methods. Source: urllib3 1.26.0 changelog The deprecated methods have been removed in urllib3 v2.0
    – Domin
    Commented May 3 at 16:28
5

A cleaner way to gain higher control might be to package the retry stuff into a function and make that function retriable using a decorator and whitelist the exceptions.

I have created the same here: http://www.praddy.in/retry-decorator-whitelisted-exceptions/

Reproducing the code in that link :

def retry(exceptions, delay=0, times=2):
"""
A decorator for retrying a function call with a specified delay in case of a set of exceptions

Parameter List
-------------
:param exceptions:  A tuple of all exceptions that need to be caught for retry
                                    e.g. retry(exception_list = (Timeout, Readtimeout))
:param delay: Amount of delay (seconds) needed between successive retries.
:param times: no of times the function should be retried


"""
def outer_wrapper(function):
    @functools.wraps(function)
    def inner_wrapper(*args, **kwargs):
        final_excep = None  
        for counter in xrange(times):
            if counter > 0:
                time.sleep(delay)
            final_excep = None
            try:
                value = function(*args, **kwargs)
                return value
            except (exceptions) as e:
                final_excep = e
                pass #or log it

        if final_excep is not None:
            raise final_excep
    return inner_wrapper

return outer_wrapper

@retry(exceptions=(TimeoutError, ConnectTimeoutError), delay=0, times=3)
def call_api():
2
  • is this for python 2.0?
    – Sam
    Commented Feb 19, 2021 at 2:41
  • This link is down now.
    – bfontaine
    Commented Nov 20, 2023 at 15:06

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.