API Rate Limit Budget
An API rate limit budget allocates a per-client request allowance over a window, so a single client cannot consume the shared capacity and the budget enforces fair use without per-request overhead.
Definition
An API rate limit budget is the allocation of a fixed number of requests per client per window — with a token bucket or fixed window counter — so that a single client cannot consume the shared backend capacity, the limit is enforced in O(1) at the edge, and the budget resets at the window boundary.
Context and scope
Applied in public APIs, multi-tenant SaaS, and any service where fair use across clients and protection against a single noisy client matter.
Common misconceptions
- Rate limiting is just a 429 — it is a 429 with a budget, a window, and a Retry-After; the response is the easy part, the budget design is the work
- A higher limit is always better for users — it is better for the limited user; for the shared backend, a too-high limit lets one client exhaust capacity
Anti-patterns
- Rate limiting per IP behind a NAT, so every user behind the corporate proxy shares one limit
- Returning 429 without Retry-After, so the client retries immediately and amplifies the load the limit was meant to protect against
Related concepts
Authoritative source
https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers
What it is
An API rate limit budget is the allocation of a fixed number of requests per client per window — with a token bucket or fixed window counter — so that a single client cannot consume the shared backend capacity, the limit is enforced in O(1) at the edge, and the budget resets at the window boundary. Applied in public APIs, multi-tenant SaaS, and any service where fair use across clients and protection against a single noisy client matter. An API is a contract, and a contract’s value is the stability that lets clients and servers evolve independently — breaking the contract breaks the clients you do not control.
How it works
Versioning makes change explicit: a new field is additive, a removed or retyped field is breaking, and the client must be able to ignore what it does not understand. Pagination, filtering, and error formats are part of the contract, not afterthoughts. Documentation is generated from the schema so it cannot drift. Deprecation gives clients a runway, marked in headers and logs, before the removal.
When to apply and pitfalls
Apply whenever more than one client consumes the interface. The pitfall is treating the API as the implementation’s reflection — changing the URL because the internal class changed, exposing database columns as fields. Another is versioning by URL path and accumulating N parallel codebases rather than versioning by capability and evolving one.