Security Rate-Limit scenarios

The following scenarios describe how rate limits are enforced for incoming requests.

Prerequisite

1. The Security module must be opted in and enabled for your domain.

Details

They illustrate system behavior when a ban is not enabled (soft limit) versus when a ban is triggered (hard limit).

Scenario 1: Soft Rate Limit (No Ban)

1. Policy Example: Limit of X requests per Y minutes per IP
2. Behavior:
   1. Requests are tracked in a rolling time window (e.g., 60 minutes).
      
   2. Up to X requests from a single IP are allowed during the window.
      
   3. Any request exceeding the limit results in a 429 Too Many Requests response.
      
   4. No ban is imposed — the IP is not blocked.
      
   5. As older requests fall out of the time window, new requests are allowed again.
      
3. Flow Example:
   1. Time 00:00 – 1st request ➜ Allowed
      
   2. Time 00:45 – Xth request ➜ Allowed
      
   3. Time 00:46 – X+1th request ➜ 429
      
   4. Time 01:01 – Oldest request expires ➜ 1 new request allowed
      

Scenario 2: Hard Rate Limit (with Ban)

1. Policy Example: Limit of X requests per Y minutes per IP ➜ Temporary ban (e.g., 15 minutes) if exceeded

2. Behavior:

   1. Similar to the soft limit: X requests are allowed within the defined window.
   2. When the limit is exceeded, the IP is temporarily banned for a fixed duration.
   3. During the ban period, all requests are blocked with 429 Too Many Requests.
   4. After the ban expires:
      1. The system re-evaluates the rolling window.
      2. If the request count still exceeds X, the IP is re-banned.
      3. If the count is below the limit, the IP is unbanned and requests resume.

3. Flow Example:

   1. Time 00:00 – 1st request ➜ Allowed
   2. Time 00:50 – Xth request ➜ Allowed
   3. Time 00:51 – X+1th request ➜ 429 + IP banned for 15 minutes
   4. Time 01:06 – Ban expires ➜ System checks window
      1. If still > X ➜ Re-ban
      2. If ≤ X ➜ Requests allowed