Python · Requests · Resilience

When Python Requests Should Wait Before Trying Again

A beginner’s guide to retries, temporary HTTP failures, and exponential back-off with requests

Main distinction

Good retry behavior starts by separating temporary failures from permanent ones.

What back-off does

It slows retries down so the client does not respond to failure with immediate repeated pressure.

Best home

Retry policy is usually cleaner on a session than scattered across individual request calls.

Introduction

A failed API request does not always mean the code is wrong. Sometimes the server is busy. Sometimes a service is briefly unavailable. Sometimes the client has sent too many requests in too short a time. That distinction matters. If every failure is treated the same way, beginner code becomes either too fragile or too aggressive. It fails too quickly, or it retries too blindly.

What makes retries easier to understand is asking a smaller question: when a request fails, is the failure permanent or temporary? That is the real fork in the road. If the failure is temporary, the right move is often not to give up immediately. It is to wait, then try again with some discipline. That is where exponential back-off becomes useful.

First version

A Single Request Is the Easy Case

Most beginner code starts with one direct request. You send it, inspect the response, and move on.

import requests


response = requests.get("https://api.example.com/data", timeout=10)
print(response.status_code)

There is nothing wrong with that as a first step. The class performing the action is the requests module. The problem is making an HTTP request and receiving a response. The constraint appears when the response is not successful and the code has no plan for what to do next.

This is similar to the role a print() statement plays in beginner debugging. It is useful for a moment, but it does not create structure. A request without retry behavior has the same temporary quality. It works until the outside system stops behaving perfectly.

Important boundary

Not Every Failure Deserves Another Try

This is the first important distinction. Some HTTP responses suggest a temporary condition. Others do not. A 429 Too Many Requests response usually means the client should slow down. A 503 Service Unavailable response often means the server is unavailable for the moment. Those are very different from a malformed request, where retrying the same bad input will not improve anything.

So the goal is not “retry everything.” The goal is narrower: retry specific failures that are likely to succeed later.

Practical takeaway Retry behavior only makes sense when the failure condition suggests that waiting could help.

Core idea

What Back-Off Actually Means

Back-off means the client does not keep retrying at the same speed after a temporary failure. It waits, and the waiting time grows with each failed attempt.

That growing pause is the key idea. If a service is already overloaded or rate-limiting the client, hammering it again immediately is rarely a good response. Exponential back-off slows the retry pattern down so the client behaves with more restraint.

For a beginner, the important point is not the adjective “exponential.” The important point is that retries should not happen in a tight loop with no delay.

Requests setup

Python Requests Can Delegate This Work

In Python, retry behavior is commonly configured through urllib3’s Retry object and attached to a requests session through an HTTPAdapter. That sounds more complicated than it is. One object describes the retry policy. Another object attaches that policy to the session.

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


retry = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[429, 503],
)

adapter = HTTPAdapter(max_retries=retry)

The class performing the action here is Retry, working through HTTPAdapter. The problem is deciding how the client should respond to temporary failures. The constraint is that retries must be selective and paced. The inverse is simple in concept: remove the retry adapter and let the request fail immediately.

Settings

What These Settings Mean

The total value controls how many retries are allowed. The backoff_factor controls how the delay grows between attempts. The status_forcelist identifies the HTTP status codes that should trigger this retry behavior.

That means the code is expressing a specific position. Try again a few times. Wait longer between each attempt. Only do this for the kinds of failures that are likely to be temporary.

Best home

The Session Is Where This Policy Belongs

Retry behavior is cleaner when it belongs to a session rather than to a scattered set of individual request calls. A session gives the code one place to say, “requests made through this connection should behave this way.”

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


session = requests.Session()

retry = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[429, 503],
)

adapter = HTTPAdapter(max_retries=retry)
session.mount("https://", adapter)

response = session.get("https://api.example.com/data", timeout=10)
print(response.status_code)

This is a better shape than rebuilding retry logic around every request. The session owns the policy. The request call benefits from it automatically.

Common examples

Why 429 and 503 Are Common Examples

These two status codes are good beginner examples because they make the idea visible. A 429 response suggests the client has crossed a rate limit. A 503 response suggests the service is temporarily unavailable. In both cases, another attempt may succeed later, but probably not if it happens immediately.

That is the logic behind the retry list. The code is not merely reacting to “error.” It is reacting to specific conditions that imply waiting may help.

Important A retry policy should react to likely temporary conditions, not to every unsuccessful response without distinction.

Different concern

This Is Not the Same Thing as Rate Limiting

It is important not to blur posts or concepts together here. Exponential back-off is not the same as proactive rate limiting. Back-off is reactive. Something failed, so the client waits and tries again. Rate limiting is proactive. The client spaces its requests out before the server has to complain.

Both ideas belong in reliable API code, but they are solving different problems. This post is only about the retry side of that boundary.

Reusable setup

A Small Helper Makes the Idea Easier to Reuse

If the same retry behavior will be used in more than one place, a helper function can keep the setup cleaner.

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


def build_session():
    session = requests.Session()

    retry = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[429, 503],
    )

    adapter = HTTPAdapter(max_retries=retry)
    session.mount("https://", adapter)
    return session


session = build_session()
response = session.get("https://api.example.com/data", timeout=10)
print(response.status_code)

That is not a major abstraction. It just prevents the retry policy from being rewritten every time the code needs a session with the same behavior.

Common mistakes

What a Beginner Should Watch Out For

The most obvious mistake is retrying too much. If the request itself is malformed, no amount of patience will repair it. Another mistake is retrying too quickly. A retry loop with no pause can make a temporary problem worse. A third mistake is treating back-off as a substitute for better pacing. If the client is regularly hitting rate limits, it may need deliberate rate limiting as well, not just better recovery after failure.

That is why this topic deserves its own post. Retry behavior is a narrower problem than general API design, and it becomes easier to understand when it is taught on its own terms.

What to keep

What a Beginner Should Keep

The most useful lesson here is not that every request needs retries. It is that some failures are temporary, and temporary failures deserve a calmer response than either immediate collapse or frantic repetition. Exponential back-off gives the client a way to respond with some discipline.

A retry policy should be selective. It should wait between attempts. It should live in one clear place, usually on the session. Once those points are clear, the pattern stops sounding advanced and starts sounding practical.

FAQ

Frequently Asked Questions

These are the practical questions beginners usually have when retry behavior and exponential back-off first start to make sense.

Should every failed request be retried?

No. Only failures that are likely to be temporary should usually be retried.

Why are 429 and 503 common retry examples?

Because they usually suggest conditions that may improve after a short wait, such as rate limiting or temporary service unavailability.

What does exponential back-off actually do?

It increases the wait time between retries so the client does not keep retrying at the same pace after failure.

Why put retry policy on a session instead of individual requests?

Because it keeps the behavior in one place and makes repeated requests through that session follow the same policy automatically.

What does `status_forcelist` control?

It defines which HTTP status codes should trigger the retry behavior.

What does `backoff_factor` control?

It affects how the delay grows between retry attempts.

Is exponential back-off the same thing as rate limiting?

No. Back-off is reactive after a failure. Rate limiting is proactive and spaces requests out before the server complains.

What is the simplest beginner rule here?

Retry selectively, wait between attempts, and keep the policy in one clear place.

Closing

No Neat Bow

Reliable request code is not built by pretending every response will be perfect. It is built by deciding what the client should do when the outside service has a temporary problem. That is all exponential back-off really is: a disciplined answer to a narrow question. Try again, but not immediately. Wait, then try with restraint.

Raell Dottin's Technical Blog