# Rate limiting

> Cap how many requests a client or a service may send per second, so one noisy caller cannot use up capacity that everyone shares.

A rate limit refuses requests above an agreed rate before they reach the service behind it.

## Use it when

- One client, bot or tenant can send far more than its share.
- A backend has a fixed ceiling, such as a paid third-party API or a database.
- You need to tell callers to slow down with a clear answer, such as HTTP 429.

## How it works

A token bucket holds tokens that refill at the limit rate. Each request takes one, and a request that finds the bucket empty is refused. The bucket's size sets the burst: a bucket of 50 with a refill of 10 per second lets a spike of 50 pass at once, then holds the average at 10. A common place for it is the gateway, so refused calls cost the services behind it nothing.

## What it costs

A limit set below real demand throws away good traffic, and one set too high protects nothing. Limits per client need an identity to count against, which costs a lookup. A refused request is still an error to the caller, so well-behaved clients must back off. Rate limiting is not [load shedding](https://wiki.playquorum.dev/patterns/load-shedding.md): a limit looks at who is sending, and shedding looks at how full the server is.

## In Quorum



The limit is a setting on an API Gateway, chosen from a short list of rates or turned off. It is one cap for the whole Gateway, not one per client. Above the limit, the Gateway answers `throttled` and the App Server never sees those requests, which is why the caption shows errors from the limit and not from capacity. The Gateway needs [API gateway](https://wiki.playquorum.dev/research/api-gateway.md). [Rate limiting](https://wiki.playquorum.dev/research/rate-limiting.md) adds a token bucket to the Gateway, so a short burst passes whole while the average holds at the limit. The glossary defines [rate limiting](https://wiki.playquorum.dev/glossary/rate-limiting.md) and the [token bucket](https://wiki.playquorum.dev/glossary/token-bucket.md). In a [Bot surge](https://wiki.playquorum.dev/incidents/bot-surge.md) the cap throttles real Users along with the bots, so the game's fix is a WAF.

Source: https://wiki.playquorum.dev/patterns/rate-limiting