Retry Requests

2.0.0 · active · verified Wed Apr 15

retry-requests is a Python library that enhances `requests.Session` objects to automatically retry failed HTTP requests. It handles transient issues like connection errors, timeouts, and specific HTTP response codes (5XX and 3XX by default) with exponential backoff. Currently at version 2.0.0, the library is actively maintained, with releases as needed based on contributions and bug fixes.

Warnings

gotcha Retrying non-idempotent methods (e.g., POST, PUT, DELETE) by default can lead to unintended side effects if the initial request succeeded on the server but the response was lost. The underlying `urllib3.Retry` (used by requests) typically excludes POST by default, but be mindful when customising `method_whitelist` or similar parameters.
Fix: Ensure that if you customize retry logic for non-GET methods, the target API endpoint is truly idempotent, or implement your own idempotency keys.
gotcha Configuring too many retries or a zero/fixed `backoff_factor` can lead to a 'retry storm' that overloads the target service, exacerbating the problem rather than solving it. This can result in IP bans or further service degradation.
Fix: Use a reasonable `retries` count (e.g., 3-5) and always apply an exponential `backoff_factor` to avoid hammering the server. Default values often provide a good starting point.
gotcha While `retry-requests` provides sensible defaults for retriable HTTP status codes (5XX, 3XX, connection errors), a common mistake is to extend `status_forcelist` to include non-transient errors like 400 Bad Request, 401 Unauthorized, or 404 Not Found. Retrying these errors will not resolve them and wastes resources.
Fix: Only retry on transient error codes (e.g., 429, 500, 502, 503, 504) and connection issues. Handle client-side errors (4XX) by checking your request parameters or authentication before retrying.

Install

pip install retry-requests Install stable version

Imports

retry
```
from retry_requests import retry
```
The primary factory function to create a retry-enabled requests Session.
TSession
```
from retry_requests import TSession
```
A convenience Session with a default timeout.
RSession
```
from retry_requests import RSession
```
A convenience Session with a timeout that always calls `raise_for_status()`.

Quickstart

Demonstrates how to create a retry-enabled requests Session using the `retry` function, both with default settings and with custom retry attempts and backoff factor. It shows how the session automatically retries on specified HTTP status codes (like 503) or connection errors.

from retry_requests import retry
from requests import Session

# Basic usage with default retries (3 retries, exponential backoff)
my_session = retry()
try:
    response = my_session.get("https://httpbin.org/status/503") # Will retry on 503
    response.raise_for_status()
    print(f"Success after retries: {response.status_code}")
except Exception as e:
    print(f"Request failed after all retries: {e}")

# Customizing retries and backoff
# Example: 5 retries, backoff factor of 0.2
custom_session = retry(Session(), retries=5, backoff_factor=0.2)
try:
    response = custom_session.get("https://httpbin.org/status/503")
    response.raise_for_status()
    print(f"Success after custom retries: {response.status_code}")
except Exception as e:
    print(f"Request failed after custom retries: {e}")

view raw JSON →