RateLimitConfig

Defines rate limiting rules to prevent API abuse and ensure fair resource usage across all consumers. Rate limiting is essential for protecting your API from being overwhelmed by too many requests, whether from legitimate heavy users, misbehaving scripts, or malicious attacks. This entity stores configurable limits that can be applied at different granularities - per user, per API key, or per IP address. Limits can be set for various time windows (requests per second, minute, hour, or day) allowing both burst tolerance and sustained usage control. For example, an API might allow 100 requests per minute with a burst of 10 requests per second. The entity supports different scopes, so you can have global limits, endpoint-specific limits, or even different limits for read versus write operations. Priority levels ensure that premium customers or critical services get higher limits. Rate limits are crucial for maintaining service stability, preventing any single consumer from monopolizing resources, and providing predictable performance for all users. They also help control costs in cloud environments where you pay for compute resources.

17 properties

Schema

Properties

Property	Type	Mode	Description	Required
entityType	string	enum	What type of entity this limit applies to Values: `user, api_key, ip_address, organization`	Required
entityId	string	stored	Specific entity identifier this limit applies to	Required
limitName	string	stored	Descriptive name for this rate limit rule Example: `"Standard API Rate Limit"`	Required
limitType	string	enum	Time window for the rate limit Values: `requests_per_second, requests_per_minute, requests_per_hour, requests_per_day, requests_per_month`	Required
limitValue	integer	stored	Maximum number of allowed requests in the time window Example: `1000`	Required
windowSize	integer	stored	Time window size in seconds Example: `3600`	Required
burstSize	integer	stored	Maximum requests allowed in a short burst	Optional
algorithm	string	enum	Rate limiting algorithm to use Values: `token_bucket, sliding_window, fixed_window, leaky_bucket`	Optional
scope	string	stored	Scope of rate limit (global, endpoint, method) Example: `"api.users.read"`	Optional
tier	string	enum	Service tier this limit applies to Values: `free, basic, premium, enterprise`	Optional
priority	integer	stored	Priority when multiple limits apply (higher wins)	Optional
responseHeaders	boolean	stored	Whether to include rate limit info in response headers	Optional
exceedAction	string	enum	What happens when limit is exceeded Values: `reject, throttle, queue, log_only`	Optional
isActive	boolean	stored	Whether this rate limit is currently enforced	Optional
bypassTokens	string	stored	Special tokens that bypass this limit	Optional
createdAt	DateTime	stored	When this rate limit was configured	Required
updatedAt	DateTime	stored	Last modification to this configuration	Optional

Examples

Example 1

{
  "@type": "RateLimitConfig",
  "entityType": "api_key",
  "entityId": "key_550e8400",
  "limitName": "Production API Standard Limit",
  "limitType": "requests_per_hour",
  "limitValue": 10000,
  "windowSize": 3600,
  "burstSize": 50,
  "algorithm": "token_bucket",
  "scope": "global",
  "tier": "premium",
  "priority": 50,
  "responseHeaders": true,
  "exceedAction": "reject",
  "isActive": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-03-01T10:00:00Z"
}

Example 2

{
  "@type": "RateLimitConfig",
  "entityType": "ip_address",
  "entityId": "203.0.113.0/24",
  "limitName": "Suspicious IP Range Throttle",
  "limitType": "requests_per_minute",
  "limitValue": 10,
  "windowSize": 60,
  "burstSize": 2,
  "algorithm": "fixed_window",
  "scope": "global",
  "priority": 100,
  "responseHeaders": false,
  "exceedAction": "throttle",
  "isActive": true,
  "createdAt": "2024-03-15T14:00:00Z"
}