Read the rate-limit headers, and hold a 429 once per client

[cubehouse]

Same treatment as ThemeParks_Python#27, same reasoning.

The SDK read exactly one header, Retry-After, and only after a 429 had already happened. It could tell you that you had run out, never that you were about to.

Both meters, on the client

import { ThemeParks, isExhausted, secondsUntilReset } from 'themeparks';

const tp = new ThemeParks({ apiKey: KEY });
await tp.entity(parkId).live();

tp.rateLimit.rest.remaining;            // 299
secondsUntilReset(tp.rateLimit.rest);   // 40
tp.rateLimit.history.remaining;         // on a history call

The per-minute REST meter, and the hourly history budget the API started publishing today.

Absence is not zero, and the design turns on it

An unmetered plan advertises no figures, and neither does a publicly cacheable response, because the numbers are per-caller and a shared cache would hand one caller's budget to another. Anonymous calls therefore carry nothing.

So null means the server did not say. isExhausted is true only when it said zero. Reading an unknown as zero would stall every anonymous client permanently, and it is the first thing the tests pin.

reset is a relative countdown frozen when it was read, so secondsUntilReset ages it. Using the raw value later is how a client waits an hour longer than it needs to — the same bug the server had in its cached headers.

It acts on what it reads

A window the server said is spent is waited out rather than walked into: that request is a certain 429 that also spends a unit of budget being refused. retry: { respectRemaining: false } opts out.

A 429 is now held once for the whole client

The wait belongs to the caller, not to whichever request met it. Ten concurrent requests each slept their own Retry-After and then retried at the same instant, re-tripping the limit together.

It goes on a shared gate with a little jitter, taken once, and the retry path no longer pays it a second time. A shorter wait arriving while a longer one is in force no longer brings the gate forward. Past maxRetryAfterMs the gate is deliberately left open: we throw instead, and blocking the caller's next call for most of an hour is the opposite of letting them checkpoint.

Verification

• 123 tests, 21 new. Mutation-checked: treating an unknown remaining as exhausted fails 3, letting a blank response erase what we knew fails 1, bringing the gate forward on a shorter wait fails 1, removing the jitter fails 1, not ageing the reset fails 2.
• Run against production: limit=300 remaining=296 reset=40 policy="300;w=60" on a real anonymous call, history meter correctly absent, isExhausted false.
• tsc, eslint, prettier and the build are clean.

One note: the cache-wrapper bug that Python hit doesn't exist here, because the client holds the inner transport directly. There's a test for it anyway — caching is on by default and every other test turns it off, which is exactly the blind spot that let it through on the Python side.

🤖 Generated with Claude Code

[cubehouse]

Held for 28 September. Decided 2026-09-26: this ships with the paid plans going live, not before. Open until then for review — ThemeParks/programme#453 carries the release steps and the deferred items.

Not a blocker on anything: the server side (tpwserver#257) has been live since the 24th and nothing depends on clients reading these headers yet. If review turns something up on the day, dropping this from the launch costs nothing.

What changed since it was opened, and why it is worth a look

Four review agents found eleven defects that the passing suite did not. In rough order of how badly they would have bitten:

Paged history crashed for every default caller	#private fields failed their brand check through the caching Proxy; every test passed cache: false (JS)
Retry-After: 0 made the client hammer	4 requests in 3ms, 204/s across ten threads, against a server actively refusing
max_retry_after bounded nothing	180s of blocking inside one call under a 120s cap; a test had encoded the bug
The documented premise was backwards	anonymous responses DO carry the per-minute figures, and they come off a CDN — measured age: 9, frozen remaining: 285
Both opt-outs did not opt out	you got the error you asked for, then your next call blocked
Two release herds	the spent-window path had zero spread: ten waiters left in the same millisecond
Three tests could not fail	including one my own monotonic-clock fix gutted

Every fix is mutation-checked and the commit messages carry the measurements. They are written to be read rather than skimmed.

Two things I would want a reviewer to push on

1. The client now sleeps on its own initiative, up to 120s, silently. Two reviewers independently said that needs at least a log line before it is the default (ThemeParks/programme#442). I left it, because both opt-outs work — but it is the judgement call most worth disagreeing with.
2. The gate is a real improvement and a partial one. Measured: refused requests halved over a sustained run, 53 → 26. But the release spread is a fixed 0.25s that does not scale, so at N=50 it is cosmetic (ThemeParks/programme#441). The docstring now records the measurement rather than the claim.