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) (key=edk) — the default. Short-lived, non-persistent, privacy-preserving.
IP address (key=ip) — hashed with SHA-256 under a random salt before storage, kept only temporarily and solely for rate-limiting.
API key (key=apiKey) — limits scoped to a specific API credential.
None (key=) — a single global limiter shared by everyone, with no per-entity distinction.

Using EDK

The EDK uses the end user's IP address and device-provided HTTP headers to compute a unique identifier for each device. In environments where users share the same network (and therefore the same IP address) and use the same or similar devices, multiple users may be identified as a single individual because they share the same EDK.

To address this issue, you can provide a seed value for EDK computation through a custom HTTP header configured using the EDK_SEED_HEADER environment variable.

The seed can be a user ID, a randomly generated cookie value, or a device fingerprint. The value should be set by your proxy to ensure that end users cannot spoof it directly.

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.