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) — 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:

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

See Security Groups for the full rule schema.

Autopilot

With 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.

Security Groups — where custom rateLimit rules live.
Autopilot — the default limiter applied automatically.
Classifier — rateLimit can also be checked inline as part of a classification request.
Privacy Protection — how EDKs and hashed IPs avoid persistent tracking.
ENV Variables — FLOOD_RATE_LIMIT reference.