Configuration properties

Complete reference for all rate limiter configuration properties

The Spring Boot Redis Rate Limiter provides several configuration properties under the ratelimiter prefix to customize its behavior.

Configuration properties

ratelimiter.enabled · boolean · default: "true"

Global switch for rate limiter auto-configuration. Set to false to completely disable the rate limiter.

ratelimiter.redis-key-prefix · string · default: "ratelimiter"

Redis key prefix used for rate-limit buckets. All rate limit counters stored in Redis will be prefixed with this value.

The final Redis key format is: {prefix}:{key}:{windowStartMillis}

ratelimiter.fail-open · boolean · default: "false"

Failure strategy when Redis is unavailable.

• false: Fail-closed (throw RateLimiterBackendException)
• true: Fail-open (allow request to proceed)

Setting this to true means requests will be allowed through when Redis is down, which may expose your API to abuse during outages.

ratelimiter.include-http-headers · boolean · default: "true"

Whether HTTP 429 responses should include rate-limit headers.

When enabled, the following headers are added to 429 responses:

• X-RateLimit-Limit: The rate limit quota
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Time when the rate limit resets
• Retry-After: Seconds until the next request can be made

ratelimiter.metrics-enabled · boolean · default: "true"

Whether Micrometer metrics should be recorded when a MeterRegistry is present.

When enabled and Micrometer is on the classpath, the rate limiter will record metrics for:

• Request evaluations (allowed vs. denied)
• Backend failures
• Per-key rate limit statistics

Configuration examples

application.properties

# Enable rate limiter (default)
ratelimiter.enabled=true

# Customize Redis key prefix
ratelimiter.redis-key-prefix=myapp:ratelimit

# Fail open when Redis is unavailable
ratelimiter.fail-open=true

# Include rate limit headers in 429 responses
ratelimiter.include-http-headers=true

# Enable metrics collection
ratelimiter.metrics-enabled=true

Minimal configuration

If you’re satisfied with the defaults, you don’t need to configure anything:

application.properties

# Only Redis connection is required
spring.data.redis.host=localhost
spring.data.redis.port=6379

The rate limiter will automatically configure itself when it detects a StringRedisTemplate bean in your application context.

Production configuration

For production environments, consider this configuration:

application.properties

# Use a descriptive key prefix
ratelimiter.redis-key-prefix=prod:api:ratelimit

# Fail closed for security (default)
ratelimiter.fail-open=false

# Include headers for client feedback
ratelimiter.include-http-headers=true

# Enable metrics for monitoring
ratelimiter.metrics-enabled=true

In production, always set fail-open: false (the default) to prevent rate limit bypass when Redis is unavailable. Monitor Redis availability closely.