Configuration Reference

Complete configuration reference for Spring AI Retry.

SpringAiRetryAutoConfiguration

Auto-configuration class for Spring Boot applications.

@AutoConfiguration
@ConditionalOnClass(RetryUtils.class)
@EnableConfigurationProperties({ SpringAiRetryProperties.class })
public class SpringAiRetryAutoConfiguration

Package: org.springframework.ai.retry.autoconfigure

Annotations:

• @AutoConfiguration - Marks as Spring Boot auto-configuration
• @ConditionalOnClass(RetryUtils.class) - Activates when spring-ai-retry is on classpath
• @EnableConfigurationProperties(SpringAiRetryProperties.class) - Enables property binding

Features:

• Automatic bean creation for Spring Boot applications
• Conditional bean registration (allows custom override)
• Property-based configuration via SpringAiRetryProperties
• WebFlux support (adds WebClientRequestException when present)

Bean Methods

retryTemplate

@Bean
@ConditionalOnMissingBean
public RetryTemplate retryTemplate(SpringAiRetryProperties properties)

Creates a configurable RetryTemplate bean.

Parameters:

• properties - Bound configuration properties

Configuration:

• Max attempts: spring.ai.retry.max-attempts (default: 10)
• Retryable exceptions: TransientAiException, ResourceAccessException, optionally WebClientRequestException
• Backoff: Exponential with configurable parameters
• Observability: RetryListener with logging

Returns: Configured RetryTemplate

Bean Override: Provide your own RetryTemplate bean to override

responseErrorHandler

@Bean
@ConditionalOnMissingBean
public ResponseErrorHandler responseErrorHandler(SpringAiRetryProperties properties)

Creates a configurable ResponseErrorHandler bean.

Parameters:

• properties - Bound configuration properties

Behavior (priority order):

1. If HTTP status in onHttpCodes → TransientAiException (retried)
2. If 4xx AND onClientErrors=false → NonTransientAiException (not retried)
3. If HTTP status in excludeOnHttpCodes → NonTransientAiException (not retried)
4. Otherwise → TransientAiException (retried)

Returns: Configured ResponseErrorHandler

Bean Override: Provide your own ResponseErrorHandler bean to override

SpringAiRetryProperties

Configuration properties class for retry behavior.

@ConfigurationProperties("spring.ai.retry")
public class SpringAiRetryProperties

Package: org.springframework.ai.retry.autoconfigure

Configuration Prefix: spring.ai.retry

Constants

public static final String CONFIG_PREFIX = "spring.ai.retry"

Configuration properties prefix.

Value: "spring.ai.retry"

Properties

maxAttempts

private int maxAttempts = 10

Maximum number of retry attempts.

Default: 10

Property: spring.ai.retry.max-attempts

Valid Range: 1 to Integer.MAX_VALUE (practical: 1-100)

Getter:

public int getMaxAttempts()

Returns the maximum number of retry attempts.

Setter:

public void setMaxAttempts(int maxAttempts)

Sets the maximum number of retry attempts.

Configuration:

spring.ai.retry.max-attempts: 5

spring.ai.retry.max-attempts=5

onClientErrors

private boolean onClientErrors = false

Controls retry behavior for 4xx client errors.

Default: false (4xx errors are non-transient)

Property: spring.ai.retry.on-client-errors

Values:

• false - 4xx errors are non-transient (not retried)
• true - 4xx errors are transient (retried)

Getter:

public boolean isOnClientErrors()

Returns whether 4xx client errors should be retried.

Setter:

public void setOnClientErrors(boolean onClientErrors)

Sets whether 4xx client errors should be retried.

Configuration:

spring.ai.retry.on-client-errors: false

spring.ai.retry.on-client-errors=false

onHttpCodes

private List<Integer> onHttpCodes = new ArrayList<>()

HTTP status codes that should always be retried (highest priority).

Default: empty list

Property: spring.ai.retry.on-http-codes

Type: java.util.List<Integer>

Priority: Evaluated first

Common Values: [429, 503, 504]

Getter:

public List<Integer> getOnHttpCodes()

Returns the list of HTTP status codes that should always be retried.

Setter:

public void setOnHttpCodes(List<Integer> onHttpCodes)

Sets the list of HTTP status codes that should always be retried.

Configuration:

spring.ai.retry.on-http-codes: [429, 503, 504]

spring.ai.retry.on-http-codes=429,503,504

excludeOnHttpCodes

private List<Integer> excludeOnHttpCodes = new ArrayList<>()

HTTP status codes that should never be retried.

Default: empty list

Property: spring.ai.retry.exclude-on-http-codes

Type: java.util.List<Integer>

Priority: Evaluated third (after onHttpCodes and onClientErrors)

Common Values: [401, 403, 404]

Getter:

public List<Integer> getExcludeOnHttpCodes()

Returns the list of HTTP status codes that should never be retried.

Setter:

public void setExcludeOnHttpCodes(List<Integer> excludeOnHttpCodes)

Sets the list of HTTP status codes that should never be retried.

Configuration:

spring.ai.retry.exclude-on-http-codes: [401, 403]

spring.ai.retry.exclude-on-http-codes=401,403

backoff

@NestedConfigurationProperty
private final Backoff backoff = new Backoff()

Exponential backoff configuration.

Property Prefix: spring.ai.retry.backoff

Type: SpringAiRetryProperties.Backoff

Getter:

public Backoff getBackoff()

Returns the backoff configuration object.

SpringAiRetryProperties.Backoff

Nested configuration class for exponential backoff parameters.

public static class Backoff

Package: org.springframework.ai.retry.autoconfigure.SpringAiRetryProperties

Properties

initialInterval

private Duration initialInterval = Duration.ofMillis(2000)

Initial sleep duration before first retry.

Default: 2000ms (2 seconds)

Property: spring.ai.retry.backoff.initial-interval

Type: java.time.Duration

Valid Range: 0ms to Long.MAX_VALUE (practical: 100ms to 10s)

Getter:

public Duration getInitialInterval()

Returns the initial backoff interval.

Setter:

public void setInitialInterval(Duration initialInterval)

Sets the initial backoff interval.

Configuration:

spring.ai.retry.backoff.initial-interval: 1000ms
# Or: 1s, PT1S

spring.ai.retry.backoff.initial-interval=1000ms
# Or: 1s

multiplier

private int multiplier = 5

Backoff interval multiplier.

Default: 5

Property: spring.ai.retry.backoff.multiplier

Valid Range: 1 to Integer.MAX_VALUE (practical: 1-10)

Common Values:

• 2 - Gentle exponential growth (2s, 4s, 8s, 16s)
• 3 - Moderate growth (2s, 6s, 18s, 54s)
• 5 - Aggressive growth (default) (2s, 10s, 50s, 250s)
• 10 - Very aggressive (2s, 20s, 200s)

Getter:

public int getMultiplier()

Returns the backoff multiplier.

Setter:

public void setMultiplier(int multiplier)

Sets the backoff multiplier.

Configuration:

spring.ai.retry.backoff.multiplier: 2

spring.ai.retry.backoff.multiplier=2

maxInterval

private Duration maxInterval = Duration.ofMillis(180000)

Maximum backoff duration (cap for exponential growth).

Default: 180000ms (3 minutes)

Property: spring.ai.retry.backoff.max-interval

Type: java.time.Duration

Must Be: >= initialInterval

Getter:

public Duration getMaxInterval()

Returns the maximum backoff interval.

Setter:

public void setMaxInterval(Duration maxInterval)

Sets the maximum backoff interval.

Configuration:

spring.ai.retry.backoff.max-interval: 30000ms
# Or: 30s, PT30S

spring.ai.retry.backoff.max-interval=30000ms
# Or: 30s

Complete Configuration Example

YAML

spring:
  ai:
    retry:
      # Retry configuration
      max-attempts: 5
      on-client-errors: false
      on-http-codes: [429, 503, 504]
      exclude-on-http-codes: [401, 403]
      
      # Backoff configuration
      backoff:
        initial-interval: 1000ms
        multiplier: 2
        max-interval: 30000ms

Properties

# Retry configuration
spring.ai.retry.max-attempts=5
spring.ai.retry.on-client-errors=false
spring.ai.retry.on-http-codes=429,503,504
spring.ai.retry.exclude-on-http-codes=401,403

# Backoff configuration
spring.ai.retry.backoff.initial-interval=1000ms
spring.ai.retry.backoff.multiplier=2
spring.ai.retry.backoff.max-interval=30000ms

Programmatic Access

import org.springframework.ai.retry.autoconfigure.SpringAiRetryProperties;
import org.springframework.beans.factory.annotation.Autowired;

@Service
public class RetryConfigService {
    
    @Autowired
    private SpringAiRetryProperties properties;
    
    public void logConfiguration() {
        logger.info("Max attempts: {}", properties.getMaxAttempts());
        logger.info("On client errors: {}", properties.isOnClientErrors());
        logger.info("On HTTP codes: {}", properties.getOnHttpCodes());
        logger.info("Exclude HTTP codes: {}", properties.getExcludeOnHttpCodes());
        logger.info("Initial interval: {}", properties.getBackoff().getInitialInterval());
        logger.info("Multiplier: {}", properties.getBackoff().getMultiplier());
        logger.info("Max interval: {}", properties.getBackoff().getMaxInterval());
    }
}

Disabling Auto-Configuration

Via Properties

spring:
  autoconfigure:
    exclude:
      - org.springframework.ai.retry.autoconfigure.SpringAiRetryAutoConfiguration

Via Annotation

@SpringBootApplication(exclude = {
    SpringAiRetryAutoConfiguration.class
})
public class Application {
    // ...
}

Property Precedence

Configuration sources in order of precedence (highest to lowest):

1. Command line arguments (--spring.ai.retry.max-attempts=5)
2. System properties (-Dspring.ai.retry.max-attempts=5)
3. Environment variables (SPRING_AI_RETRY_MAX_ATTEMPTS=5)
4. application-{profile}.yml or application-{profile}.properties
5. application.yml or application.properties
6. Default values in SpringAiRetryProperties

Environment-Specific Configuration

Development

spring:
  profiles: dev
  ai:
    retry:
      max-attempts: 2
      backoff:
        initial-interval: 100ms
        max-interval: 1s

Production

spring:
  profiles: prod
  ai:
    retry:
      max-attempts: 10
      on-http-codes: [429, 503, 504]
      backoff:
        initial-interval: 2s
        multiplier: 5
        max-interval: 180s

Testing

spring:
  profiles: test
  ai:
    retry:
      max-attempts: 3
      backoff:
        initial-interval: 10ms
        max-interval: 100ms

Next Steps

• API Reference - Complete API documentation
• Exception Reference - Exception types and classification
• Configuration Guide - Configuration scenarios and examples