---

Location: RateLimitingUtil.scala

Purpose: Main rate limiting enforcement function called for every API request

Flow:

Logic:

1. Check if CallContext exists
2. Determine if consumer is authenticated (authorized) or anonymous
3. Authorized path:
   • Retrieve rate limits from CallContext.rateLimiting
   • Check all 6 time periods using underConsumerLimits()
   • If any limit exceeded - Return 429 error with appropriate message
   • If all checks pass - Increment all counters using incrementConsumerCounters()
   • Set X-Rate-Limit-* headers
4. Anonymous path:
   • Check only PER_HOUR limit
   • Use IP address as rate limiting key
   • If limit exceeded - Return 429 error
   • Otherwise increment counter and continue

Error Precedence: Shorter periods take precedence in error messages:

Purpose: Check if consumer is under limit for a specific time period

Logic:

1. If use_consumer_limits=false - Return true (allow)
2. If limit <= 0 - Return true (unlimited)
3. If limit > 0:
   • Build Redis key: {consumerKey}_{period}
   • Check if key EXISTS in Redis
   • If exists: GET current count, check if count + 1 <= limit
   • If not exists: Return true (first call in window)
4. Return result (true = under limit, false = exceeded)

Exception Handling: Catches all Redis exceptions and returns true (fail-open)

Purpose: Increment Redis counter for a specific time period

Logic:

1. If limit == -1 - DELETE the Redis key, return (-1, -1)
2. If limit > 0:
   • Build Redis key
   • Check TTL of key
   • If TTL == -2 (key doesn't exist):
     • Initialize with SETEX key ttl "1"
     • Return (ttl_seconds, 1)
   • If key exists:
     • Atomically increment with INCR key
     • Return (remaining_ttl, new_count)
3. Return tuple: (TTL_remaining, call_count)

Return Values:

• (-1, -1): Unlimited or error
• (ttl, count): Active limit with remaining time and current count

Purpose: Read current state of all rate limit counters (for reporting/debugging)

Returns: Sequence of tuples containing:

• Option[Long]: Current call count
• Option[Long]: Remaining TTL
• LimitCallPeriod: The time period

Used by: API endpoints that report rate limit status to consumers

---

The system sets three standard HTTP headers on successful responses:

Header	Description	Example
X-Rate-Limit-Limit	Maximum requests allowed in period	1000
X-Rate-Limit-Remaining	Requests remaining in current window	732
X-Rate-Limit-Reset	Seconds until limit resets (TTL)	2847

When multiple periods are active, headers reflect the most restrictive active period:

When rate limit is exceeded:

Message Format:

• Authorized: "Too Many Requests. We only allow {limit} requests {period} for this Consumer."
• Anonymous: "Too Many Requests. We only allow {limit} requests {period} for anonymous access."

---

Useful Redis commands for monitoring rate limiting:

Enable debug logging in logback.xml:

Log Examples:

Check Redis connectivity:

Usage:

---

The system uses a fail-open approach for resilience:

Rationale: If Redis is unavailable, the API remains functional rather than blocking all requests.

Symptoms:

• Logs show: Redis issue: redis.clients.jedis.exceptions.JedisConnectionException
• All rate limit checks return true (allow)
• Rate limiting is effectively disabled

Resolution:

1. Check Redis server is running: redis-cli ping
2. Verify network connectivity
3. Check Redis credentials and SSL configuration
4. Review connection pool settings
5. Monitor connection pool exhaustion

Check:

Cause: Multiple API instances with separate Redis instances

Solution: Ensure all API instances connect to the same Redis instance

Check TTL:

Fix:

Check:

Cause: Keys created without TTL

Prevention: Always use SETEX (not SET) for rate limit counters

---

Operation	Time Complexity	Performance Impact
GET	O(1)	Negligible
SET	O(1)	Negligible
SETEX	O(1)	Negligible
INCR	O(1)	Negligible
TTL	O(1)	Negligible
EXISTS	O(1)	Negligible
DEL	O(1)	Negligible

Per Request Cost:

• Authorized: ~12-18 Redis operations (6 checks + 6 increments)
• Anonymous: ~2-3 Redis operations (1 check + 1 increment)

Typical Redis RTT: 0.1-1ms (same datacenter)

Per Request Latency:

• Authorized: 1.2-18ms
• Anonymous: 0.2-3ms

Deploy Redis on the same network/datacenter as OBP-API instances to minimize network latency.

The default pool configuration is optimized for high throughput:

• 128 max connections supports 128 concurrent requests
• Adjust based on your load profile

Estimate memory usage:

Monitor:

The current implementation checks all 6 periods sequentially. Future optimization could use Redis pipelining:

Horizontal Scaling:

• Multiple OBP-API instances - Same Redis instance
• Redis becomes a potential bottleneck at very high scale

Redis Scaling Options:

1. Redis Sentinel: High availability with automatic failover
2. Redis Cluster: Horizontal sharding for massive scale
3. Redis Enterprise: Commercial solution with advanced features

Capacity Planning:

• Single Redis instance: 50,000-100,000 ops/sec
• With 6 ops per authorized request: ~8,000-16,000 requests/sec
• With 2 ops per anonymous request: ~25,000-50,000 requests/sec

---

Response:

Response:

---

The Redis-based rate limiting system in OBP-API provides:

Distributed rate limiting across multiple API instances Multi-period enforcement (second, minute, hour, day, week, month) Automatic expiration via Redis TTL Atomic operations for thread-safety Fail-open reliability when Redis is unavailable Standard HTTP headers for client awareness Flexible configuration via properties and database records Anonymous access control based on IP address

Key Files:

• code/api/util/RateLimitingUtil.scala - Main rate limiting logic
• code/api/cache/Redis.scala - Redis connection abstraction
• code/api/AfterApiAuth.scala - Integration point in request flow

Configuration:

• use_consumer_limits=true - Enable rate limiting
• cache.redis.url / cache.redis.port - Redis connection
• user_consumer_limit_anonymous_access - Anonymous limits

Monitoring:

• Redis CLI: KEYS *_PER_*, GET, TTL
• Application logs: Enable DEBUG on RateLimitingUtil
• API headers: X-Rate-Limit-*