RateLimitState
Tracks the real-time state of rate limits for active API consumers, maintaining counters and timestamps for enforcement decisions. While RateLimitConfig defines the rules, this entity stores the actual runtime data - how many requests have been made, when the current window started, and when it will reset. This separation allows for efficient, high-performance rate limiting even at massive scale. The entity implements various algorithms like token bucket (where tokens regenerate over time) or sliding window (tracking exact request times). For the token bucket algorithm, it tracks available tokens and when they were last refilled. The system updates this state on every API request, using optimistic locking to handle concurrent requests safely. When limits are exceeded, the isThrottled flag is set, and the system can return appropriate HTTP 429 (Too Many Requests) responses with headers indicating when the client can retry. This real-time tracking is typically implemented in fast storage like Redis for production systems, but this entity provides the persistent record for debugging, analytics, and system recovery after restarts.
Properties
| Property | Type | Mode | Description | Required |
|---|---|---|---|---|
| entityType | string | enum | Type of entity being rate limited Values: | Required |
| entityId | string | stored | Identifier of the entity being tracked | Required |
| bucket | string | stored | Rate limit bucket identifier (combines entity and scope) Example: | Required |
| requestCount | integer | stored | Number of requests in current window | Optional |
| windowStart | DateTime | stored | Start of the current rate limit window | Required |
| windowEnd | DateTime | stored | End of the current rate limit window | Required |
| tokensAvailable | integer | stored | Remaining tokens in token bucket algorithm | Optional |
| tokenCapacity | integer | stored | Maximum tokens in the bucket | Optional |
| refillRate | number | stored | Tokens added per second | Optional |
| lastRefillAt | DateTime | stored | Last time tokens were added to bucket | Optional |
| resetAt | DateTime | stored | When this rate limit window resets | Required |
| isThrottled | boolean | stored | Whether entity is currently being throttled | Optional |
| throttledAt | DateTime | stored | When throttling started | Optional |
| throttleCount | integer | stored | Number of rejected requests while throttled | Optional |
| lastRequestAt | DateTime | stored | Timestamp of the most recent request | Optional |
| peakRequestRate | number | stored | Highest requests/second observed in this window | Optional |
| version | integer | stored | Version for optimistic locking during updates | Optional |
| updatedAt | DateTime | stored | Last time this state was modified | Required |
Examples
Example 1
{
"@type": "RateLimitState",
"entityType": "api_key",
"entityId": "key_550e8400",
"bucket": "api_key:550e8400:global",
"requestCount": 847,
"windowStart": "2024-03-15T14:00:00Z",
"windowEnd": "2024-03-15T15:00:00Z",
"tokensAvailable": 153,
"tokenCapacity": 1000,
"refillRate": 0.28,
"lastRefillAt": "2024-03-15T14:30:00Z",
"resetAt": "2024-03-15T15:00:00Z",
"isThrottled": false,
"lastRequestAt": "2024-03-15T14:30:45Z",
"peakRequestRate": 12.5,
"version": 847,
"updatedAt": "2024-03-15T14:30:45Z"
}Example 2
{
"@type": "RateLimitState",
"entityType": "ip_address",
"entityId": "203.0.113.45",
"bucket": "ip:203.0.113.45:auth",
"requestCount": 10,
"windowStart": "2024-03-15T14:29:00Z",
"windowEnd": "2024-03-15T14:30:00Z",
"resetAt": "2024-03-15T14:30:00Z",
"isThrottled": true,
"throttledAt": "2024-03-15T14:29:30Z",
"throttleCount": 25,
"lastRequestAt": "2024-03-15T14:29:55Z",
"peakRequestRate": 5,
"version": 35,
"updatedAt": "2024-03-15T14:29:55Z"
}