# Rate Limiters

Rate Limiters cap how many requests a given key — a device, an IP, an API key, or nothing at all — can make within a time window, throttling abusive traffic before it becomes a bigger problem.

## Syntax

The basic format is `{requests}/{duration}`:

| Example | Meaning |
|---|---|
| `100/1s` | 100 requests per second |
| `100/5m` | 100 requests per 5 minutes |
| `100/1h` | 100 requests per hour |
| `100/1d` | 100 requests per day |
| `100/1w` | 100 requests per week |

### Modifiers

Add optional parameters in parentheses, combined with `&`:

| Modifier | Purpose | Example |
|---|---|---|
| `alert` | Trigger a notification when the limit is exceeded | `100/1h(alert)` or `100/1h(alert=custom_message)` |
| `key` | Override the default key type | `100/1h(key=ip)` |
| `code` | Custom error code on the 429 response | `100/1h(code=TOO_MANY_REQUESTS)` |
| `log` | Disable logging when this limit triggers | `100/1h(log=false)` |
| `headers` | Disable `X-Ratelimit-*` response headers | `100/1h(headers=false)` |

```
100/1h(key=ip&alert=Too many requests&code=429_TOO_MANY)
```

## Key types

- **[Ephemeral Device Key (EDK)](/docs/sentinel/security/privacy-protection/#ephemeral-device-keys-edk)** — the default. Short-lived, non-persistent, privacy-preserving.
- **IP address** — hashed with SHA-256 under a random salt before storage, kept only temporarily and solely for rate-limiting.
- **API key** — limits scoped to a specific API credential.
- **None** — a single global limiter shared by everyone, with no per-entity distinction.

## Configuring in a Security Group

Set the `rateLimit` field with a `set` rule:

```json
{
"name": "Rate Limiter",
"action": "set",
"conditions": [],
"set": [{ "field": "rateLimit", "value": "100/1h" }]
}
```

See [Security Groups](/docs/sentinel/configure/security-groups/#schema) for the full rule schema.

## Autopilot

With [Autopilot](/docs/sentinel/features/autopilot/) enabled, a default rate limiter (50 requests/10 minutes per EDK) is applied to all incoming requests automatically. A custom `rateLimit` rule overrides this default.

## Flood protection

Independent of Security Group rules, Sentinel also runs an early-stage flood limiter — evaluated before any database query — on public/unauthenticated endpoints. Configure it with `FLOOD_RATE_LIMIT` (default `100/1m`); set it empty to disable, which is useful when [benchmarking](/docs/sentinel/operations/performance-tuning/#benchmarks).

## Related

- [Security Groups](/docs/sentinel/configure/security-groups/) — where custom `rateLimit` rules live.
- [Autopilot](/docs/sentinel/features/autopilot/) — the default limiter applied automatically.
- [Classifier](/docs/sentinel/features/classifier/#using-the-api) — `rateLimit` can also be checked inline as part of a classification request.
- [Privacy Protection](/docs/sentinel/security/privacy-protection/) — how EDKs and hashed IPs avoid persistent tracking.
- [ENV Variables](/docs/sentinel/operations/env-variables/#rate-limiting--proof-of-work) — `FLOOD_RATE_LIMIT` reference.