rate-limitinglisted

# Rate Limiting, Usage & Recovery Most of what follows was expensive to derive — some of it from production log forensics — and is not obvious from the code, which contains at least one comment that is provably wrong (see `references/429-signals.md` § Disproven comments). ## The mental model in one paragraph Anthropic reports account usage as a set of **windows** (5h, weekly, …) via a state endpoint we **poll**. It separately rejects individual requests with 429s carrying headers that describe *why*. When a 429 means the account itself is spent, the proxy writes a **cooldown** (`rate_limited_until`) that removes the account from routing until a deadline. Everything the dashboard shows is a **projection** of that state — it never feeds routing. An account comes back either when its cooldown expires, or when polling observes the quota recovered. ## The 429 decision ladder `proxy-operations.ts`, in order: ``` reprobe → out_of_credits (long floor, no burst-retry) → account-wide exhausted (weekly OR 5h session spent; no burst-retry) → family-weekly safety net (fails over WITHOUT an account-wide cooldown; cache evidence first — with the cache UNAVAILABLE it can read the 429's own scoped unified headers, e.g. `7d_oi` rejected while 5h/7d show headroom) → transparent burst-retry (classify429Transient → hold & re-probe) → model fallback / no-fallback / all-mode