跳到正文
DEV Community· Jack Ma·· 1 小時前AI 評分65

兩種 429,以及 requests、got 和 ky 如何處理 Retry-After

Two kinds of 429, and what requests, got and ky do with Retry-After

AI 導讀

作者比較 Node 26.3.0 的 fetch、requests 2.34.2、got 16.2.0 和 ky 2.2.0,指出相同的 429 與 Retry-After 會觸發不同重試行為,等待時間本身也不能可靠區分速率限制和用量配額。

正文

A 429 can mean "slow down for a second" or "you've used up this month's allowance". The status code is the same for both, and none of the four HTTP clients I tested tries to tell them apart. I wanted to know what a 429 should carry so that the caller can. I read the RFCs first. Then I pointed the clients at a local server that sent a 429 with either a one-second or a 30-day Retry-After.

For either limit, return 429, say in the response which limit the caller hit, and set Retry-After to match. That's what slide 3 of a six-slide deck on per-customer API rate limiting recommends. The RFCs cover the status and the wait, not which limit it was.

What the specs give you

RFC 6585 defines 429 as the user having "sent too many requests in a given amount of time". The response SHOULD explain the condition and MAY include Retry-After. The RFC's own example is a limit of 50 requests an hour, answered with Retry-After: 3600. It doesn't say how you count or over what period, so a monthly quota fits the definition as well as a per-second burst does. One rule people forget: a 429 MUST NOT be stored by a cache.

Retry-After is defined in RFC 9110, section 10.2.3. It's either an HTTP date or a number of seconds, and the seconds form is a non-negative decimal integer, so 1.5 isn't valid. That section only spells out what the field means on a 503 or a redirect. Its use on a 429 comes from RFC 6585.

The RateLimit-Policy and RateLimit fields are still an Internet-Draft (draft-ietf-httpapi-ratelimit-headers, a working group document in the IETF HTTPAPI group), and the syntax changed again in November. Draft-11, from 23 May 2026, writes the current state as RateLimit: "default";r=50;t=30. Draft-12, published on 20 November 2026, renames those parameters: RateLimit: default;a=50;w=30, where a is the available quota and is required. A client written against draft-12 that gets draft-11 output finds no a, and the draft says malformed RateLimit fields MUST be ignored. Both versions agree on one client rule: if a response has both RateLimit and Retry-After, Retry-After wins.

The draft also defines a problem type for the body, https://iana.org/assignments/http-problem-types#quota-exceeded, with a violated-policies array. It isn't in IANA's problem type registry yet, and it doesn't settle the question anyway. It's for requests that "exceed one or more Quota Policies", and a 10-per-second policy is a quota policy as much as a monthly one is. To tell the limits apart from violated-policies, the client needs to know which policy names refer to rate limits and which refer to billing quotas.

What clients do with Retry-After

The test server is about 50 lines of Python's http.server. For the table below it sent one 429 with the chosen Retry-After, then a 200. For the retry-limit tests further down it kept sending 429s. It logged every request. The clients ran with default settings unless noted: the built-in fetch in Node 26.3.0, requests 2.34.2 on urllib3 2.8.0, got 16.2.0 and ky 2.2.0.

                             Retry-After: 1                Retry-After: 2592000 (30 days)
fetch                        429, no retry                 429, no retry
requests, default session    429, no retry                 429, no retry
requests + Retry(total=3)    GET: waits 1 s, then 200      GET: asks to sleep 6 hours (stubbed)
got                          GET: waits 1 s, then 200      GET: throws HTTPError 429 at once
ky                           GET: waits 1 s, then 200      GET: still waiting after 5 s

fetch and a plain requests session hand you the 429 and stop. I mounted an HTTPAdapter with Retry(total=3) and left status_forcelist empty, and the GET still retried, because urllib3 treats 413, 429 and 503 as retryable when they carry Retry-After. HTTPAdapter(max_retries=3) did the same, since requests turns the integer into a Retry. The same 429 without the header came back after one request. A POST wasn't retried with or without the header, since POST isn't in urllib3's default list of retryable methods. got and ky behaved the same way for POST.

For the 30-day case in urllib3 I swapped out time.sleep in its retry module for a function that records the argument. urllib3 asked for 21,600 seconds. Retry has a retry_after_max setting that defaults to six hours, and the source comment says that "matches other popular libraries". If every retry gets the same 429 and header, that six-hour sleep repeats until total runs out. With Retry(retry_after_max=60) the stub recorded 60 seconds, and the retry still went out.

got threw at once on the 30-day value, but not because it recognised a quota. Its docs say that delays above 2,147,483,647 ms, Node's timer limit of about 24.8 days, abort the retry. With a 25-day Retry-After it threw too. With a one-day or 24-day header it was still waiting when I stopped watching after five seconds. got skips the retry when the server asks for longer than retry.maxRetryAfter, and if that's unset it uses timeout.request as the limit. With either set to less than a day, the one-day 429 came straight back.

ky was still waiting five seconds into the 30-day test. With ky 2.2.0's defaults, maxRetryAfter is Infinity, and the source caps the scheduled delay at Node's timer limit of about 24.8 days, after which it retries. Setting maxRetryAfter: 2000 didn't make it give up. It waited 2 seconds and sent the retry. got and ky use the same option name for opposite behaviour: got treats it as "don't retry if the server asks for longer than this", ky as "never wait longer than this, then retry". totalTimeout: 3000 did stop ky, with a TimeoutError after 3 seconds. If Retry-After is missing, ky checks RateLimit-Reset, X-RateLimit-Retry-After, X-RateLimit-Reset and X-Rate-Limit-Reset for a delay.

Telling them apart

You could classify by the size of Retry-After: a few seconds means a rate limit, days means a quota. I tried that rule against what UsageRail's SDK actually sends, and it breaks. A quota 429 there says Retry-After: 1 in the last second of a billing period. It also says 1 when concurrent requests on one server use up that server's share of the quota before the next share arrives, and in that case a retry a second later can succeed. A quota with no period end sends no Retry-After at all. In my GET tests with repeated 429s and no timing headers at all, got and ky each made two more requests with backoff, while urllib3 with Retry(total=3) and no status_forcelist stopped after the first 429.

What works is a stable code in the body. These are the two 429s UsageRail's SDK sends. With the clock frozen, I ran 11 checks against limits of 10 per second and 300 per minute. That gave me the first example's headers, and its JSON is the SDK's default error body. The quota example comes from the docs:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
RateLimit-Policy: "per_second";q=10;w=1, "per_minute";q=300;w=60
RateLimit: "per_second";r=0;t=1, "per_minute";r=290;t=2

{"error":"rate_limited","retry_after":1}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1036800

{"error":"quota_exceeded","retry_after":1036800}

The RateLimit values there use draft-11 syntax and have no a, which draft-12 requires, so a draft-12 parser will skip that field. RateLimit-Policy still parses under draft-12. For how long to wait, clients should go by Retry-After. If you're writing the client, the cheat sheet on API rate limit headers and 429 handling lists when to retry each kind of 429, the status codes, and both Retry-After formats.

RFC 6585 makes Retry-After optional. A long delay can leave urllib3 asleep for hours and ky waiting longer. Without timing headers, got and ky still retried in my tests, and clients need the body to learn when the quota resets. I'd send the header when I know when the quota resets, repeat the value in the body, and have clients read the error code before deciding whether to wait.

I tested this with a plain requests.Session(), so the function handles retries itself. Pass it a session with a urllib3 Retry mounted and the adapter may sleep and retry before the function ever sees the 429. It waits at most 30 seconds per retry, and retries quota_exceeded only if it can parse a Retry-After of 30 seconds or less:

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

import requests

MAX_WAIT = 30  # the longest this caller is willing to sleep, in seconds


class QuotaExceeded(Exception):
    pass


def retry_after_seconds(value):
    if value is None:
        return None
    if value.strip().isdigit():
        return int(value)
    try:
        when = parsedate_to_datetime(value)
        return max(0, (when - datetime.now(timezone.utc)).total_seconds())
    except (TypeError, ValueError):
        return None  # not a number or a date we can compare: treat as missing


def error_code(response):
    try:
        return response.json().get("error")
    except (ValueError, AttributeError):
        return None


def get(session, url, attempts=4):
    for attempt in range(attempts):
        response = session.get(url)
        if response.status_code != 429:
            return response
        code = error_code(response)
        wait = retry_after_seconds(response.headers.get("Retry-After"))
        if code == "quota_exceeded" and (wait is None or wait > MAX_WAIT):
            raise QuotaExceeded(f"quota used up, Retry-After: {wait}")
        if wait is None:
            wait = random.uniform(0, min(MAX_WAIT, 0.5 * 2**attempt))
        if wait > MAX_WAIT:
            raise RuntimeError(f"429 {code}, Retry-After {wait}s is longer than {MAX_WAIT}s")
        if attempt + 1 < attempts:
            time.sleep(wait)
    return response

Against the test server, with Retry-After: 1 both rate_limited and quota_exceeded got a 200 on the next request, a second later. With no header, rate_limited used jittered backoff and got a 200 on the third request, while quota_exceeded raised QuotaExceeded after one request. With a 30-day header, quota_exceeded raised the same exception and an unknown code raised RuntimeError, both after one request. A 429 that never cleared came back after four requests, with no sleep after the last one. The body can also be an HTML page from a proxy rather than your JSON, which is why error_code returns None instead of raising.

If your server doesn't run an SDK, the same split still applies. UsageRail's HTTP check endpoint, for example, answers your server with a 200 whose JSON has a code and a retry_after, and your server writes the 429 itself. For rate_limited or quota_exceeded, put the code in the body and copy retry_after into Retry-After when it's a number. For a quota that's usually the seconds until the period resets, but it can be a short wait of 1, or null.

These results are from one machine on 22 November 2026, with the versions above. Retry defaults change between releases, so check the ones you depend on.

I work on UsageRail.

I used AI to help draft this post.

來源:DEV Community · dev.to