HTTP Status Codes Cheat Sheet

Quick decision table

1xx Informational

You rarely see these: HTTP libraries handle them before handing you the final response.

2xx Success

3xx Redirection

• requests follows redirects by default (except for requests.head()); a 302 or 303 turns POST into GET, and so does a 301 for POST.
• httpx does not follow redirects unless you pass follow_redirects=True.
• Redirect loops raise TooManyRedirects. A redirect to a login or consent page usually means your session or cookies are missing.
• response.history (requests) lists every hop; check it when a "200" page looks wrong.

4xx Client errors

5xx Server errors

Non-standard codes you will meet

Cloudflare 52x codes are origin problems: retry later with backoff. A Cloudflare challenge usually comes as 403 or 503 with a cf-mitigated: challenge header or a challenge HTML page.

Retry rules

• Retry only idempotent requests (GET, HEAD, PUT, DELETE, OPTIONS) automatically. Retrying a POST can create duplicates unless the API supports an Idempotency-Key header.
• Use exponential backoff with jitter and a cap on attempts and on total wait.
• Retry-After is either seconds (120) or an HTTP date. Honour it on 429 and 503.
• Back off per host: when one URL gets a 429, every worker hitting that host should slow down.
• Always set a timeout. requests waits forever by default; httpx defaults to 5 seconds.

requests + urllib3 Retry

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

retry = Retry(
    total=5,
    backoff_factor=1,                     # urllib3 2.x sleeps 0, 2, 4, 8, 16 s (max 120 s)
    status_forcelist=[429, 500, 502, 503, 504],
    allowed_methods=["GET", "HEAD", "OPTIONS"],   # POST is never retried here
    respect_retry_after_header=True,      # default; applies to 413, 429, 503
)
session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=retry))
session.mount("http://", HTTPAdapter(max_retries=retry))

resp = session.get(url, timeout=(5, 30))  # (connect, read) seconds
resp.raise_for_status()                   # turn 4xx/5xx into exceptions

When the retries run out on a listed status, requests raises requests.exceptions.RetryError.

Parsing Retry-After yourself

import random
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime

def retry_after_seconds(value, default=None):
    # Retry-After is delta-seconds ("120") or an HTTP-date.
    if not value:
        return default
    if value.strip().isdigit():
        return int(value)
    try:
        when = parsedate_to_datetime(value)
    except (TypeError, ValueError):
        return default
    return max(0.0, (when - datetime.now(timezone.utc)).total_seconds())

def backoff(attempt, base=1.0, cap=60.0):
    # Exponential backoff with full jitter.
    return random.uniform(0, min(cap, base * 2 ** attempt))