\documentclass[10pt,a4paper]{article} % Packages \usepackage{fancyhdr} % For header and footer \usepackage{multicol} % Allows multicols in tables \usepackage{tabularx} % Intelligent column widths \usepackage{tabulary} % Used in header and footer \usepackage{hhline} % Border under tables \usepackage{graphicx} % For images \usepackage{xcolor} % For hex colours %\usepackage[utf8x]{inputenc} % For unicode character support \usepackage[T1]{fontenc} % Without this we get weird character replacements \usepackage{colortbl} % For coloured tables \usepackage{setspace} % For line height \usepackage{lastpage} % Needed for total page number \usepackage{seqsplit} % Splits long words. %\usepackage{opensans} % Can't make this work so far. Shame. Would be lovely. \usepackage[normalem]{ulem} % For underlining links % Most of the following are not required for the majority % of cheat sheets but are needed for some symbol support. \usepackage{amsmath} % Symbols \usepackage{MnSymbol} % Symbols \usepackage{wasysym} % Symbols %\usepackage[english,german,french,spanish,italian]{babel} % Languages % Document Info \author{SuperLede} \pdfinfo{ /Title (api-rate-limit-headers-and-429-handling.pdf) /Creator (Cheatography) /Author (SuperLede) /Subject (API Rate Limit Headers and 429 Handling Cheat Sheet) } % Lengths and widths \addtolength{\textwidth}{6cm} \addtolength{\textheight}{-1cm} \addtolength{\hoffset}{-3cm} \addtolength{\voffset}{-2cm} \setlength{\tabcolsep}{0.2cm} % Space between columns \setlength{\headsep}{-12pt} % Reduce space between header and content \setlength{\headheight}{85pt} % If less, LaTeX automatically increases it \renewcommand{\footrulewidth}{0pt} % Remove footer line \renewcommand{\headrulewidth}{0pt} % Remove header line \renewcommand{\seqinsert}{\ifmmode\allowbreak\else\-\fi} % Hyphens in seqsplit % This two commands together give roughly % the right line height in the tables \renewcommand{\arraystretch}{1.3} \onehalfspacing % Commands \newcommand{\SetRowColor}[1]{\noalign{\gdef\RowColorName{#1}}\rowcolor{\RowColorName}} % Shortcut for row colour \newcommand{\mymulticolumn}[3]{\multicolumn{#1}{>{\columncolor{\RowColorName}}#2}{#3}} % For coloured multi-cols \newcolumntype{x}[1]{>{\raggedright}p{#1}} % New column types for ragged-right paragraph columns \newcommand{\tn}{\tabularnewline} % Required as custom column type in use % Font and Colours \definecolor{HeadBackground}{HTML}{333333} \definecolor{FootBackground}{HTML}{666666} \definecolor{TextColor}{HTML}{333333} \definecolor{DarkBackground}{HTML}{1F5A6B} \definecolor{LightBackground}{HTML}{F1F4F5} \renewcommand{\familydefault}{\sfdefault} \color{TextColor} % Header and Footer \pagestyle{fancy} \fancyhead{} % Set header to blank \fancyfoot{} % Set footer to blank \fancyhead[L]{ \noindent \begin{multicols}{3} \begin{tabulary}{5.8cm}{C} \SetRowColor{DarkBackground} \vspace{-7pt} {\parbox{\dimexpr\textwidth-2\fboxsep\relax}{\noindent \hspace*{-6pt}\includegraphics[width=5.8cm]{/web/www.cheatography.com/public/images/cheatography_logo.pdf}} } \end{tabulary} \columnbreak \begin{tabulary}{11cm}{L} \vspace{-2pt}\large{\bf{\textcolor{DarkBackground}{\textrm{API Rate Limit Headers and 429 Handling Cheat Sheet}}}} \\ \normalsize{by \textcolor{DarkBackground}{SuperLede} via \textcolor{DarkBackground}{\uline{cheatography.com/219377/cs/48597/}}} \end{tabulary} \end{multicols}} \fancyfoot[L]{ \footnotesize \noindent \begin{multicols}{3} \begin{tabulary}{5.8cm}{LL} \SetRowColor{FootBackground} \mymulticolumn{2}{p{5.377cm}}{\bf\textcolor{white}{Cheatographer}} \\ \vspace{-2pt}SuperLede \\ \uline{cheatography.com/superlede} \\ \end{tabulary} \vfill \columnbreak \begin{tabulary}{5.8cm}{L} \SetRowColor{FootBackground} \mymulticolumn{1}{p{5.377cm}}{\bf\textcolor{white}{Cheat Sheet}} \\ \vspace{-2pt}Published 21st November, 2026.\\ Updated 21st November, 2026.\\ Page {\thepage} of \pageref{LastPage}. \end{tabulary} \vfill \columnbreak \begin{tabulary}{5.8cm}{L} \SetRowColor{FootBackground} \mymulticolumn{1}{p{5.377cm}}{\bf\textcolor{white}{Sponsor}} \\ \SetRowColor{white} \vspace{-5pt} %\includegraphics[width=48px,height=48px]{dave.jpeg} Measure your website readability!\\ www.readability-score.com \end{tabulary} \end{multicols}} \begin{document} \raggedright \raggedcolumns % Set font size to small. Switch to any value % from this page to resize cheat sheet text: % www.emerson.emory.edu/services/latex/latex_169.html \footnotesize % Small font. \begin{multicols*}{2} \begin{tabularx}{8.4cm}{x{3.04 cm} x{4.96 cm} } \SetRowColor{DarkBackground} \mymulticolumn{2}{x{8.4cm}}{\bf\textcolor{white}{Pick the status code}} \tn % Row 0 \SetRowColor{LightBackground} `400` Bad Request & Malformed request: bad JSON, a missing field. Resending it unchanged gets the same answer \tn % Row Count 4 (+ 4) % Row 1 \SetRowColor{white} `401` Unauthorized & No key, unknown key, revoked key. RFC 9110 requires a `WWW-Authenticate` field on a 401, e.g. `WWW-Authenticate: Bearer` \tn % Row Count 9 (+ 5) % Row 2 \SetRowColor{LightBackground} `402` Payment Required & Prepaid credits ran out. The spec still reserves 402 "for future use", so say why in the body \tn % Row Count 13 (+ 4) % Row 3 \SetRowColor{white} `403` Forbidden & The key is valid but this customer may not do this: account suspended, endpoint not on their plan \tn % Row Count 18 (+ 5) % Row 4 \SetRowColor{LightBackground} `429` Too Many Requests & Over a rate limit or a quota (RFC 6585). Send `Retry-After` when you know when a retry can work \tn % Row Count 22 (+ 4) % Row 5 \SetRowColor{white} `503` Service Unavailable & Your side can't serve the request: overloaded, or a dependency is down. `Retry-After` works here too \tn % Row Count 27 (+ 5) % Row 6 \SetRowColor{LightBackground} \mymulticolumn{2}{x{8.4cm}}{401, 402, 403: the customer fixes something before retrying. 429: check the error code and any `Retry-After`. 503: the problem is on your side.} \tn % Row Count 30 (+ 3) \hhline{>{\arrayrulecolor{DarkBackground}}--} \end{tabularx} \par\addvspace{1.3em} \begin{tabularx}{8.4cm}{x{2.48 cm} x{5.52 cm} } \SetRowColor{DarkBackground} \mymulticolumn{2}{x{8.4cm}}{\bf\textcolor{white}{What a 429 should carry}} \tn % Row 0 \SetRowColor{LightBackground} \seqsplit{`Retry-After`} & If present, wait this long before retrying. Seconds or an HTTP date (see Retry-After: two formats) \tn % Row Count 4 (+ 4) % Row 1 \SetRowColor{white} \seqsplit{`RateLimit-Policy`} & Each limit: `q` = quota, `w` = window in seconds \tn % Row Count 6 (+ 2) % Row 2 \SetRowColor{LightBackground} `RateLimit` & Each limit now: `r` = available quota, `t` (optional) = how many seconds that quota applies for \tn % Row Count 10 (+ 4) % Row 3 \SetRowColor{white} Body & A stable error code, e.g. `rate\_limited`, plus `retry\_after` (see Example 429). Human-readable text is optional \tn % Row Count 15 (+ 5) % Row 4 \SetRowColor{LightBackground} \seqsplit{Content-Type} & `application/json` as in Example 429, or an RFC 9457 Problem Details body:\{\{nl\}\}`application/`\{\{nl\}\}`problem+json` \tn % Row Count 20 (+ 5) % Row 5 \SetRowColor{white} 2xx responses & You can send the `RateLimit` fields on success too, so clients slow down before they run out \tn % Row Count 24 (+ 4) \hhline{>{\arrayrulecolor{DarkBackground}}--} \SetRowColor{LightBackground} \mymulticolumn{2}{x{8.4cm}}{`RateLimit-Policy` and `RateLimit` come from the IETF draft \seqsplit{draft-ietf-httpapi-ratelimit-headers}. The examples use draft-11. Draft-12 (November 2026) uses `a` for available quota and `w` for the window in `RateLimit`; `RateLimit-Policy` keeps `q` and `w`. Check which draft your clients support.\{\{nl\}\}Draft-06 and earlier used `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. Non-standard `X-RateLimit-*` headers vary by API: `Reset` can be seconds left or a Unix timestamp.} \tn \hhline{>{\arrayrulecolor{DarkBackground}}--} \end{tabularx} \par\addvspace{1.3em} \begin{tabularx}{8.4cm}{X} \SetRowColor{DarkBackground} \mymulticolumn{1}{x{8.4cm}}{\bf\textcolor{white}{Example 429}} \tn \SetRowColor{LightBackground} \mymulticolumn{1}{x{8.4cm}}{HTTP/1.1 429 Too Many Requests \newline Content-Type: application/json \newline Retry-After: 1 \newline RateLimit-Policy: "per\_second";q=10;w=1 \newline RateLimit-Policy: "per\_minute";q=300;w=60 \newline RateLimit: "per\_second";r=0;t=1 \newline RateLimit: "per\_minute";r=212;t=18 \newline \newline \{"error": "rate\_limited", "retry\_after": 1\}} \tn \hhline{>{\arrayrulecolor{DarkBackground}}-} \SetRowColor{LightBackground} \mymulticolumn{1}{x{8.4cm}}{UsageRail's example, draft-11 syntax. Each field can also be sent as one line with the two limits comma-separated. The per-second bucket is empty. The per-minute bucket has 212 of 300 tokens; here `t=18` is how long it takes to refill if no more requests arrive.} \tn \hhline{>{\arrayrulecolor{DarkBackground}}-} \end{tabularx} \par\addvspace{1.3em} \begin{tabularx}{8.4cm}{x{2.16 cm} x{5.84 cm} } \SetRowColor{DarkBackground} \mymulticolumn{2}{x{8.4cm}}{\bf\textcolor{white}{Retry-After: two formats}} \tn % Row 0 \SetRowColor{LightBackground} Delay & `Retry-After: 120`\{\{nl\}\}Whole seconds, a non-negative integer \tn % Row Count 3 (+ 3) % Row 1 \SetRowColor{white} HTTP date & `Retry-After:`\{\{nl\}\}`Sat, 21 Nov 2026 07:00:00 GMT`\{\{nl\}\}IMF-fixdate, always GMT \tn % Row Count 6 (+ 3) % Row 2 \SetRowColor{LightBackground} Servers & Send seconds. A date depends on the client's clock agreeing with yours \tn % Row Count 9 (+ 3) % Row 3 \SetRowColor{white} Round up & `Math.ceil`. Rounding down sends the client back a moment early, into another 429 \tn % Row Count 12 (+ 3) % Row 4 \SetRowColor{LightBackground} Clients & Parse both. For a date, wait until that time; if it's already past, wait 0 \tn % Row Count 15 (+ 3) % Row 5 \SetRowColor{white} Where it's used & 503 and 3xx (RFC 9110, section 10.2.3), and 429 (RFC 6585) \tn % Row Count 17 (+ 2) \hhline{>{\arrayrulecolor{DarkBackground}}--} \end{tabularx} \par\addvspace{1.3em} \begin{tabularx}{8.4cm}{x{1.292 cm} x{2.432 cm} x{3.876 cm} } \SetRowColor{DarkBackground} \mymulticolumn{3}{x{8.4cm}}{\bf\textcolor{white}{Two kinds of 429}} \tn % Row 0 \SetRowColor{LightBackground} & {\bf{Rate limit}} & {\bf{Quota used up}} \tn % Row Count 2 (+ 2) % Row 1 \SetRowColor{white} \seqsplit{Window} & e.g. a second or a minute & e.g. a billing period \tn % Row Count 5 (+ 3) % Row 2 \SetRowColor{LightBackground} \seqsplit{`Retry-After`} & e.g. 1–60 s & If supplied, seconds until reset, e.g. `86400` \tn % Row Count 8 (+ 3) % Row 3 \SetRowColor{white} \seqsplit{Example} code & \seqsplit{`rate\_limited`} & `quota\_exceeded` \tn % Row Count 10 (+ 2) % Row 4 \SetRowColor{LightBackground} \seqsplit{Client} \seqsplit{should} & Back off and retry & Stop, tell the user, upgrade or wait \tn % Row Count 13 (+ 3) \hhline{>{\arrayrulecolor{DarkBackground}}---} \SetRowColor{LightBackground} \mymulticolumn{3}{x{8.4cm}}{A 429 alone can mean "wait a second" or "come back next month". I work on UsageRail; its Node SDK puts the reason in an `error` field: `rate\_limited` or `quota\_exceeded` on a 429, `insufficient\_credits` on a 402.} \tn \hhline{>{\arrayrulecolor{DarkBackground}}---} \end{tabularx} \par\addvspace{1.3em} \begin{tabularx}{8.4cm}{X} \SetRowColor{DarkBackground} \mymulticolumn{1}{x{8.4cm}}{\bf\textcolor{white}{Client retry rules}} \tn % Row 0 \SetRowColor{LightBackground} \mymulticolumn{1}{x{8.4cm}}{{\bf{1.}} If you retry, wait at least as long as `Retry-After` says. It takes precedence over the `RateLimit` window.} \tn % Row Count 3 (+ 3) % Row 1 \SetRowColor{white} \mymulticolumn{1}{x{8.4cm}}{{\bf{2.}} Safe to retry and no `Retry-After`: exponential backoff with full jitter.\{\{nl\}\}`sleep = random(0,`\{\{nl\}\}` min(cap, base × 2\textasciicircum{}attempt))`} \tn % Row Count 6 (+ 3) % Row 2 \SetRowColor{LightBackground} \mymulticolumn{1}{x{8.4cm}}{{\bf{3.}} e.g. base 0.5 s, cap 30 s, give up after 5 attempts.} \tn % Row Count 8 (+ 2) % Row 3 \SetRowColor{white} \mymulticolumn{1}{x{8.4cm}}{{\bf{4.}} Jitter matters. Clients that hit the limit together otherwise retry together and hit it again.} \tn % Row Count 11 (+ 3) % Row 4 \SetRowColor{LightBackground} \mymulticolumn{1}{x{8.4cm}}{{\bf{5.}} Retry 429 `rate\_limited`, 502, 503, 504 and dropped connections for idempotent requests (GET, PUT, DELETE). A POST only if the server honours an idempotency key, resent with the same key.} \tn % Row Count 15 (+ 4) % Row 5 \SetRowColor{white} \mymulticolumn{1}{x{8.4cm}}{{\bf{6.}} No automatic retries on 400, 401, 402, 403, 404, 422. Send it again once the cause is fixed: a refreshed token, topped-up credits, a resource that now exists.} \tn % Row Count 19 (+ 4) % Row 6 \SetRowColor{LightBackground} \mymulticolumn{1}{x{8.4cm}}{{\bf{7.}} On `quota\_exceeded`, stop automatic retries. Show the reset time if the API provides one.} \tn % Row Count 21 (+ 2) % Row 7 \SetRowColor{white} \mymulticolumn{1}{x{8.4cm}}{{\bf{8.}} Every retry is a new request, and the API may count it against your limit or bill it.} \tn % Row Count 23 (+ 2) \hhline{>{\arrayrulecolor{DarkBackground}}-} \end{tabularx} \par\addvspace{1.3em} \begin{tabularx}{8.4cm}{x{2.16 cm} x{5.84 cm} } \SetRowColor{DarkBackground} \mymulticolumn{2}{x{8.4cm}}{\bf\textcolor{white}{Per-customer vs global limits}} \tn % Row 0 \SetRowColor{LightBackground} \seqsplit{Per-customer} & One bucket per customer. A noisy customer runs out of their own allowance, not everyone's \tn % Row Count 4 (+ 4) % Row 1 \SetRowColor{white} Global & One bucket for the whole API. Protects your servers, does nothing for fairness \tn % Row Count 7 (+ 3) % Row 2 \SetRowColor{LightBackground} Key on & The customer behind the API key, after authentication. Not the IP: customers behind one NAT share an IP \tn % Row Count 11 (+ 4) % Row 3 \SetRowColor{white} Before auth & A coarse per-IP limit is fine for unauthenticated routes (sign-up, key creation) \tn % Row Count 14 (+ 3) % Row 4 \SetRowColor{LightBackground} Token bucket & Capacity sets the largest burst; the refill rate sets sustained traffic. For 10 requests/s, refill a token every 100 ms; a capacity of 10 allows a burst of 10 \tn % Row Count 20 (+ 6) % Row 5 \SetRowColor{white} Several servers & In-memory buckets count per process. With 4 servers at 10/s each, one customer whose traffic is spread evenly gets up to 40/s. Split the limit across servers or use a shared counter \tn % Row Count 27 (+ 7) % Row 6 \SetRowColor{LightBackground} Restarts & In-memory buckets start full after a deploy: expect one extra burst \tn % Row Count 30 (+ 3) \end{tabularx} \par\addvspace{1.3em} \vfill \columnbreak \begin{tabularx}{8.4cm}{x{2.16 cm} x{5.84 cm} } \SetRowColor{DarkBackground} \mymulticolumn{2}{x{8.4cm}}{\bf\textcolor{white}{Per-customer vs global limits (cont)}} \tn % Row 7 \SetRowColor{LightBackground} \mymulticolumn{2}{x{8.4cm}}{The \{\{link="https://usagerail.com/docs/rate-limits"\}\}per-customer API rate limiting\{\{/link\}\} docs explain the two-bucket 429 from Example 429 and why a 10/s limit split across four servers can still let about 12/s through.} \tn % Row Count 5 (+ 5) \hhline{>{\arrayrulecolor{DarkBackground}}--} \end{tabularx} \par\addvspace{1.3em} \begin{tabularx}{8.4cm}{x{2.96 cm} x{5.04 cm} } \SetRowColor{DarkBackground} \mymulticolumn{2}{x{8.4cm}}{\bf\textcolor{white}{When the limiter is down}} \tn % Row 0 \SetRowColor{LightBackground} \mymulticolumn{2}{x{8.4cm}}{Applies when the limit check is a network call (a shared counter store, a rate limit service).} \tn % Row Count 2 (+ 2) % Row 1 \SetRowColor{white} Timeout & Short, e.g. 500 ms. Every checked request waits for the limiter \tn % Row Count 5 (+ 3) % Row 2 \SetRowColor{LightBackground} Fail open & Serve the request without a limit decision. It may go over the limit or go uncounted \tn % Row Count 9 (+ 4) % Row 3 \SetRowColor{white} Fail closed & Answer 503, with `Retry-After` if you can estimate recovery. Nothing unchecked is served, and the limiter's outage becomes your customers' outage \tn % Row Count 15 (+ 6) % Row 4 \SetRowColor{LightBackground} Choosing & Open for cheap reads your backend can absorb. Closed if one unchecked call can run up a bill \tn % Row Count 19 (+ 4) % Row 5 \SetRowColor{white} Don't retry the check & A check that timed out may already have been counted. If the retry is allowed too, both count \tn % Row Count 23 (+ 4) % Row 6 \SetRowColor{LightBackground} Limiter says 400 or 401 & Your config is wrong (bad app key, bad parameter). Log it and answer 500; don't pass a 401 to your customer \tn % Row Count 28 (+ 5) % Row 7 \SetRowColor{white} \mymulticolumn{2}{x{8.4cm}}{Log every fail-open, so you know how much went through unchecked.} \tn % Row Count 30 (+ 2) \hhline{>{\arrayrulecolor{DarkBackground}}--} \end{tabularx} \par\addvspace{1.3em} \begin{tabularx}{8.4cm}{X} \SetRowColor{DarkBackground} \mymulticolumn{1}{x{8.4cm}}{\bf\textcolor{white}{Minimal 429 in Express}} \tn \SetRowColor{LightBackground} \mymulticolumn{1}{x{8.4cm}}{// Per-customer token bucket. Runs after authenticate \newline // has set req.customerId. In memory, per process. \newline const CAPACITY = 10; // burst size \newline const REFILL\_PER\_SEC = 1; // steady rate \newline const buckets = new Map(); \newline \newline function rateLimit(req, res, next) \{ \newline const now = performance.now() / 1000; \newline const bucket = \seqsplit{buckets.get(req.customerId)} \newline ?? \{ tokens: CAPACITY, updatedAt: now \}; \newline bucket.tokens = Math.min(CAPACITY, bucket.tokens \newline + (now - bucket.updatedAt) * REFILL\_PER\_SEC); \newline bucket.updatedAt = now; \newline \seqsplit{buckets.set(req.customerId}, bucket); \newline \newline if (bucket.tokens \textless{} 1) \{ \newline const wait = Math.ceil( \newline (1 - bucket.tokens) / REFILL\_PER\_SEC); \newline res.set('Retry-After', String(wait)); \newline return res.status(429).json( \newline \{ error: 'rate\_limited', retry\_after: wait \}); \newline \} \newline bucket.tokens -= 1; \newline next(); \newline \} \newline \newline app.use(authenticate, rateLimit);} \tn \hhline{>{\arrayrulecolor{DarkBackground}}-} \SetRowColor{LightBackground} \mymulticolumn{1}{x{8.4cm}}{Behind a test route that returns 200: send 11 requests from one customer within a second and the 11th gets 429 with `Retry-After: 1`, while a second customer still gets 200. `performance.now()` is monotonic, so a wall-clock jump can't refill every bucket at once.} \tn \hhline{>{\arrayrulecolor{DarkBackground}}-} \end{tabularx} \par\addvspace{1.3em} % That's all folks \end{multicols*} \end{document}