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

[cubehouse]

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

tp.rate_limit.rest.remaining              # 299
tp.rate_limit.history.remaining           # on a history call
tp.rate_limit.rest.seconds_until_reset()

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

Absence is not zero, and the whole 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 None means the server did not say. .exhausted 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 seconds_until_reset() 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 costs a unit of budget to be refused. RetryConfig(respect_remaining=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 — a thundering herd the client inflicted on itself, and on us.

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

Two things worth calling out

Production found a bug my tests could not. Caching is on by default and wraps the transport; every test passed cache=False, so the first real call raised AttributeError — the caching wrapper had no rate_limit to forward. Tests that all take the same non-default path cover a shape the users do not have. Fixed, and pinned by a test that fails if the forwarding is removed.

One mutation survived the first battery. Removing a prefix filter from the REST read changed no behaviour and no test. It was redundant: the lookups are by exact key, so RateLimit-Limit and RateLimit-History-Limit cannot collide. The dead guard is gone rather than the test being bent around it.

Verification

• 210 tests, 23 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 5.
• Run against production: reads limit=300 remaining=299 reset=60 policy='300;w=60' on a real anonymous call, with the history meter correctly absent and exhausted=False.
• ruff, mypy --strict and mkdocs build --strict clean.

JavaScript gets the same treatment next.

🤖 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.