> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitem.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Leaky Bucket

> Burst in. Steady out. Overflow rejects.

The bucket has capacity `limit`. Each allowed request adds 1. The bucket leaks at `limit / duration`. If adding this request would overflow, it's rejected.

Unlike token bucket, you don't get an instant burst of `limit` from a full (empty) start — you fill from zero.

## When to use it

Traffic shaping. You want bursty clients to become a smooth stream, and you want to reject anything above that stream.

## vs token bucket

|          | Token bucket            | Leaky bucket                     |
| -------- | ----------------------- | -------------------------------- |
| Starts   | Full                    | Empty                            |
| Burst    | Spend up to `limit` now | Queue up to `limit`, then reject |
| Recovery | Tokens refill           | Level leaks                      |

## Shape

<ResponseField name="remaining" type="number">
  Space left in the bucket after this request.
</ResponseField>

<ResponseField name="reset_time" type="number">
  Allowed: when the bucket will be empty. Rejected: when there will be space for one more request.
</ResponseField>