Rate Limiters

Rate limiters allow you to control the number of requests a device or user can make within a specified time period. This mechanism is essential for preventing excessive or abusive traffic directed at the API endpoints.

Resources

• Security Groups

Feature Highlights

• Conditional rate limiting: Apply limits based on specific rules or criteria.
• Customizable behavior: Tailor keys, alerts, and response codes to suit your needs.

Use Cases

• Prevent request flooding on public API endpoints.
• Limit validations per device or IP address.
• Control request volume for external services.

Autopilot

When Autopilot is enabled, a default rate limiter is automatically applied to all incoming requests. This provides a basic level of protection by default, without requiring any additional configuration.

You can override this default rate limiter by defining a set rule that specifies a new rateLimit value. This allows you to customize the rate-limiting behavior to better suit your application’s needs.

Global Flood-Preventing Limiter

The server includes a built-in rate limiter designed to protect against request flooding by malicious actors. This limiter is applied early in the request lifecycle—before any database queries or compute-intensive operations are executed—ensuring that abusive traffic is rejected as early as possible.

You can configure the flood protection threshold by setting the FLOOD_RATE_LIMIT environment variable. This limit applies only to public or unauthenticated endpoints.

Configuration

To define a custom rate limiter, configure a new Security Group Rule. The example below sets a rate limit of 100/1h (100 requests per hour) and applies it globally to all users:

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

Keys

Rate limiters are associated with a key, which uniquely identifies each limiter instance. By default, this key corresponds to an Ephemeral Device Key (EDK), ensuring compliance with privacy regulations while allowing per-device tracking without personal data exposure.

However, you can customize the key type using Security Group Rules with the set action and specifying the key field.

Supported Key Types

• Ephemeral Device Key (EDK) – Default
• IP Address
• API Key
• No key (global rate limiter)

Definition Format

Rate limiters are defined using the format {requests}/{duration}. For example, 100/1h allows 100 requests within a one-hour window.

Duration Examples

Format	Description
100/1s	100 requests per second
100/5m	100 requests per 5 minutes
100/2h	100 requests per 2 hours
100/1d	100 requests per day
100/1w	100 requests per week (7 days)

Advanced Parameters

For greater control, you can specify additional parameters inside parentheses:

• Alert: Triggers an alert when the limit is exceeded. Optionally provide a custom message:

  • 100/1h(alert)
  • 100/1h(alert=custom_message)

• Key: Override the default key used for rate limiting:

  • 100/1h(key=ip)
  • Allowed values: apiKey, ip, edk, or empty string for global scope.

• Code: Define a custom error code returned upon hitting the limit:

  • 100/1h(code=TOO_MANY_REQUESTS)

Example with multiple parameters:

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

Ephemeral Device Keys (EDK)

To ensure ALTCHA Sentinel adheres to strict data-privacy regulations, the system uses Ephemeral Device Keys (EDKs) — short-lived, non-persistent identifiers designed for rate-limiting and security enforcement.

IP Addresses as Keys

When using IP addresses as rate-limiting keys, each IP is first hashed using a cryptographic algorithm (SHA-256) combined with a random salt. This process pseudonymizes the IP address, ensuring it is not stored in its original form.

The resulting hash is stored temporarily (e.g., in an in-memory store like Redis) solely for rate-limiting purposes and is automatically discarded after a short expiration period.