---
title: "What is the Retry-After header?"
url: https://proxy.wiki/glossary/retry-after/
type: Glossary Term
author: "proxy.wiki editorial"
published: 2026-09-06
updated: 2026-10-21
site: proxy.wiki
topics: ["Web scraping"]
license: CC BY 4.0; quote freely with attribution to https://proxy.wiki/
---

# What is the Retry-After header?

> Retry-After is an HTTP response header telling the client how long to wait, in seconds or until an HTTP-date, before trying again.

When a server sends it, it is the only retry timing you will get from the party that actually knows the answer. Waiting less than it asks is the quickest way to turn a temporary limit into a lasting block, and it wastes the request as well.

## Two forms, one header

RFC 9110 allows either a number of seconds or an HTTP-date, and gives one example of each:

```
Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
Retry-After: 120
```

The seconds form is a non-negative integer counted from receipt of the response, so it needs no clock agreement at all. The date form names an instant, which means the client has to decide what time it is now. That decision is where implementations differ.

## Which responses carry it

| Response | What the specification says | Honoured by urllib3 2.3.0 by default |
| --- | --- | --- |
| 503 Service Unavailable | The server MAY send it to say how long the service is expected to be unavailable (RFC 9110) | Yes |
| 429 Too Many Requests | The response MAY include it (RFC 6585) | Yes |
| 413 Content Too Large | If the condition is temporary, the server SHOULD send it (RFC 9110) | Yes |
| Any 3xx redirect | The minimum wait before following the redirect (RFC 9110) | No |

None of these require the header, so a server that omits it is not misbehaving. Treat its absence as no information and fall back to [exponential backoff](/glossary/exponential-backoff/) with jitter and a cap.

## What a client library does with it

We tested Python’s requests 2.32.3 with urllib3 2.3.0 on 21 October 2026 against a local server that answered `429` with `Retry-After: 3` twice, then `200`. A session with `Retry(total=3, backoff_factor=0.5)` mounted waited 3.01 seconds and then 3.00 seconds, returning the 200 after 6.01 seconds. Its own backoff schedule would have waited 0 and then 1 second. A plain `requests.get()` with no Retry mounted returned the 429 immediately, because requests retries nothing by default.

The date form is handled less carefully. urllib3’s `parse_retry_after` subtracts `time.time()`, the local clock, from the date the server sent. A client whose clock runs a few minutes fast will wait a few minutes too little, possibly zero. Measuring against the response’s own `Date` header removes the skew, since both values then come from the server’s clock:

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

def retry_after_seconds(headers):
    """Seconds to wait, or None if the response gave no instruction."""
    value = headers.get("Retry-After", "").strip()
    if not value:
        return None
    if value.isdigit():
        return int(value)
    when = parsedate_to_datetime(value)
    date = headers.get("Date")
    now = parsedate_to_datetime(date) if date else datetime.now(timezone.utc)
    return max(0.0, (when - now).total_seconds())

print(retry_after_seconds({"Retry-After": "120"}))
print(retry_after_seconds({"Retry-After": "Fri, 31 Dec 1999 23:59:59 GMT",
                           "Date": "Fri, 31 Dec 1999 23:57:59 GMT"}))
print(retry_after_seconds({}))
```

```
$ python3 retry_after.py        # Python 3.15.0 and 3.9.6 print the same
120
120.0
None
```

One more trap: code that passes the header straight to `float()` works for months against servers that send seconds, then raises `ValueError` the first time a server sends a date.

## Rotating the address does not reset the wait

Switching to a new [exit node](/glossary/exit-node/) to ignore the wait helps only when the limit is keyed to the address. When it is keyed to an account, a session cookie or an API token, the new exit changes nothing except your bandwidth bill. The rule of thumb in [how rotation interacts with rate limits](/guides/rotating-vs-sticky-sessions/#interaction-with-rate-limits) is to change pacing first and rotation second. Rotating at the same speed also spends pool reputation across many addresses instead of pausing one, a point made in [the 429 section of 403 vs 407 vs 429](/guides/403-vs-407-vs-429/#429-too-many-requests).

Log the value you were given next to the value you actually waited. A gap between the two is the first thing to check when a job that used to finish starts collecting blocks, and your own logs can answer it without touching the target. A working retry loop that honours the header is in [retries that do not make things worse](/guides/proxies-in-python-requests-httpx/#retries-that-do-not-make-things-worse).

The `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers seen on some APIs are conventions with no standard behind them, no agreed units and no promise of presence. Read them when they exist; never make your client depend on them.

## Frequently asked questions

### Which takes priority, Retry-After or my own backoff schedule?

Retry-After. It is the server stating what it will tolerate. Wait at least that long, and apply your own backoff on top only if the next attempt also fails. urllib3 does the same for 413, 429 and 503.

### Is a missing Retry-After header a server bug?

No. RFC 9110 and RFC 6585 allow it on these responses without requiring it, so a correct server may omit it. Treat its absence as no information and fall back to capped exponential backoff with jitter.

## Sources

1. [RFC 9110: HTTP Semantics, Retry-After (10.2.3), 413 (15.5.14) and 503 (15.6.4)](https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after)
2. [RFC 6585: 429 Too Many Requests and its optional Retry-After](https://www.rfc-editor.org/rfc/rfc6585.html)
3. [urllib3 documentation: Retry, respect_retry_after_header and RETRY_AFTER_STATUS_CODES](https://urllib3.readthedocs.io/en/stable/reference/urllib3.util.html)
