Spring AI Retry

Spring AI Retry provides comprehensive retry mechanisms specifically designed for AI API interactions within the Spring AI framework. It offers pre-configured retry templates with exponential backoff strategies for handling transient failures when communicating with AI model providers, custom exception hierarchies for classifying retryable and non-retryable errors, and a specialized ResponseErrorHandler that automatically categorizes HTTP errors from AI services.

Package Information

• Package Name: org.springframework.ai:spring-ai-retry
• Package Type: Maven
• Language: Java
• Group ID: org.springframework.ai
• Artifact ID: spring-ai-retry (core) and spring-ai-autoconfigure-retry (Spring Boot auto-configuration)
• Version: 1.1.2

Installation:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-retry</artifactId>
    <version>1.1.2</version>
</dependency>

For Spring Boot with auto-configuration:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-autoconfigure-retry</artifactId>
    <version>1.1.2</version>
</dependency>

Quick Start

Basic Usage with Static Constants

import org.springframework.ai.retry.RetryUtils;
import org.springframework.retry.support.RetryTemplate;
import org.springframework.web.client.RestTemplate;

// Configure RestTemplate with error handler
RestTemplate restTemplate = new RestTemplate();
restTemplate.setErrorHandler(RetryUtils.DEFAULT_RESPONSE_ERROR_HANDLER);

// Use retry template for API calls
RetryTemplate retryTemplate = RetryUtils.DEFAULT_RETRY_TEMPLATE;
String response = retryTemplate.execute(context -> {
    return restTemplate.postForEntity(aiApiUrl, request, String.class);
});

Spring Boot Auto-Configuration

spring:
  ai:
    retry:
      max-attempts: 5
      on-http-codes: [429, 503, 504]
      backoff:
        initial-interval: 1s
        multiplier: 2
        max-interval: 30s

@Service
public class AiService {
    
    @Autowired
    private RetryTemplate retryTemplate;
    
    @Autowired
    private ResponseErrorHandler responseErrorHandler;
    
    public String callAi(String prompt) {
        return retryTemplate.execute(context -> 
            aiClient.generate(prompt)
        );
    }
}

Core Components

RetryUtils

Utility class providing pre-configured retry templates and error handlers.

Static Members:

• DEFAULT_RETRY_TEMPLATE - Production retry template (10 attempts, exponential backoff: 2s → 180s)
• SHORT_RETRY_TEMPLATE - Testing retry template (10 attempts, fixed 100ms backoff)
• DEFAULT_RESPONSE_ERROR_HANDLER - HTTP error handler (4xx → non-transient, 5xx → transient)

Exception Types

TransientAiException: Thrown for temporary failures that may succeed on retry (5xx errors, network issues, rate limits). Automatically retried by RetryTemplate.

NonTransientAiException: Thrown for permanent failures that require intervention (4xx errors, auth failures, invalid requests). Not retried.

Auto-Configuration

SpringAiRetryAutoConfiguration: Automatically creates RetryTemplate and ResponseErrorHandler beans for Spring Boot applications, configurable via spring.ai.retry.* properties.

Quick Reference

Error Classification (DEFAULT_RESPONSE_ERROR_HANDLER)

Backoff Timing (DEFAULT_RETRY_TEMPLATE)

Configuration Properties

Documentation

Guides

• Quick Start Guide - Detailed getting started guide with setup and basic usage
• Configuration Guide - Comprehensive configuration scenarios and best practices

Examples

• Integration Patterns - Real-world integration patterns and advanced usage
• Error Handling Strategies - Comprehensive error handling examples
• Edge Cases and Pitfalls - Common pitfalls and edge case handling

Reference

• API Reference - Complete API documentation with all methods and signatures
• Configuration Reference - Detailed configuration properties and auto-configuration
• Exception Reference - Exception types and error classification details
• Type Reference - External types and dependencies

Common Use Cases

Use Case 1: Basic AI API with Retry

RetryTemplate template = RetryUtils.DEFAULT_RETRY_TEMPLATE;
String result = template.execute(context -> aiClient.generate(prompt));

Use Case 2: Retry with Fallback

String result = retryTemplate.execute(
    context -> aiClient.generate(prompt),
    recoveryContext -> cachedResponseService.getLastKnownGood(prompt)
);

Use Case 3: Custom Retry Configuration

spring:
  ai:
    retry:
      max-attempts: 3
      on-http-codes: [503, 504]
      backoff:
        initial-interval: 500ms
        multiplier: 2
        max-interval: 5s

Core Concepts

Transient vs Non-Transient Errors

Transient: Temporary failures that may succeed on retry without changes (network issues, service outages, rate limits). The retry template automatically retries these.

Non-Transient: Permanent failures requiring code or configuration changes (invalid API key, malformed request, insufficient permissions). These fail immediately without retry.

Exponential Backoff

Retry delays increase exponentially to avoid overwhelming failing services:

• Start with short delay (2 seconds)
• Multiply by factor (5x) on each retry
• Cap at maximum interval (3 minutes)
• Prevents thundering herd problem

Error Handler Integration

The ResponseErrorHandler automatically classifies HTTP errors:

1. Checks response status code
2. Throws appropriate exception type (Transient vs NonTransient)
3. RetryTemplate retries only TransientAiException
4. NonTransientAiException propagates immediately

Thread Safety

All components are thread-safe and can be shared across threads:

• RetryUtils.DEFAULT_RETRY_TEMPLATE - Thread-safe
• RetryUtils.SHORT_RETRY_TEMPLATE - Thread-safe
• RetryUtils.DEFAULT_RESPONSE_ERROR_HANDLER - Stateless and thread-safe
• Auto-configured beans - Spring singleton beans are thread-safe

Each execute() call creates a new RetryContext, so retry state is isolated per execution.

Dependencies

Required:

• spring-retry - Core retry functionality
• spring-web - HTTP client infrastructure
• slf4j-api - Logging

Optional:

• spring-boot-autoconfigure - For auto-configuration support
• spring-webflux - Enables WebClientRequestException retry support

See Also

• Spring Retry Documentation
• Spring AI Documentation
• Resilience Patterns