Backing off as a client: Retry-After, RateLimit headers and per-host budgets

Goal

Stay inside a server's limits without guessing, recover from a limit hit without making it worse, and keep an agent's many small requests from turning into an outage for the service or a ban for the key.

Prerequisites

A client that can inspect status codes and headers, sleep, and keep a little state per host. Knowledge of which requests are idempotent.

Steps

1. On 429 Too Many Requests (RFC 6585) or 503 Service Unavailable, look for Retry-After. RFC 9110 defines it as either a number of seconds or an HTTP date; wait that long, then retry once. A Retry-After is the server's instruction and overrides any local schedule.
2. Without Retry-After, back off exponentially from a base delay with full jitter, cap the delay, and cap the number of attempts. Count attempts per request, not per session, and give up with a clear error once the cap is reached.
3. Read advisory headers when present. The IETF draft on RateLimit header fields defines a RateLimit field carrying the remaining quota and the seconds until reset, and a RateLimit-Policy field describing the quota policy; a client that reads them can slow down before the first 429. Treat them as hints that may be absent or change shape between servers, and fall back to step 2.
4. Keep a budget per host and per credential: a maximum number of in-flight requests and a minimum interval, adjusted downwards on every 429 and upwards only slowly. Parallel agents sharing one key share one budget; coordinate through a shared counter or a queue rather than each backing off independently.
5. Never retry a non-idempotent write blindly. Attach an idempotency key when the API supports one, so that a retry after a timeout cannot duplicate the effect; otherwise query for the effect before retrying.
6. Log every 429 with the host, the endpoint class and the wait applied; a pattern of 429s on one endpoint is a design signal (fetch less, cache more, use a batch endpoint), not a reason to raise the retry cap.
7. Prefer conditional requests and caching for reads: a 304 Not Modified is cheap for both sides and usually not counted against a quota in the same way as a full response, though that is the server's policy to state.

Expected result

Limit hits become rare and self-correcting, retries never duplicate a write, and the service sees a client that slows down when asked rather than one that hammers harder.

Limits and test basis

Standards synthesis and a proposed client discipline; no measurement. The RateLimit header draft is a draft: field names and semantics may change until publication, and many servers send their own vendor-specific headers instead.