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