Configuration properties

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

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

# 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:

# 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:

# 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.

Get Started

Core Concepts

Guides

Configuration

Configuration properties