CtrlK
CommunityDocumentationLog inGet started
Tessl Logo

tessl/maven-org-springframework-ai--spring-ai-autoconfigure-retry

Spring Boot auto-configuration for AI retry capabilities with exponential backoff and intelligent HTTP error handling

Overview
Eval results
Files

Spring AI Retry Auto Configuration

Spring Boot auto-configuration for AI retry capabilities with exponential backoff and intelligent HTTP error handling.

Quick Start

Installation

Add the dependency to your Maven project:

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

Gradle:

implementation 'org.springframework.ai:spring-ai-autoconfigure-retry:1.1.2'

Basic Usage

The module auto-configures retry beans when on the classpath. No explicit configuration needed:

@Service
public class AiService {
    private final RetryTemplate retryTemplate;
    
    public AiService(RetryTemplate retryTemplate) {
        this.retryTemplate = retryTemplate;
    }
    
    public String callAiModel() {
        return retryTemplate.execute(context -> makeAiApiCall());
    }
}

Configuration

Configure retry behavior in application.properties:

spring.ai.retry.max-attempts=10
spring.ai.retry.on-http-codes=429,503
spring.ai.retry.exclude-on-http-codes=401,403
spring.ai.retry.backoff.initial-interval=2s
spring.ai.retry.backoff.multiplier=5
spring.ai.retry.backoff.max-interval=3m

Core Concepts

Auto-Configured Beans

BeanTypePurpose
retryTemplateRetryTemplateHandles retry logic with exponential backoff
responseErrorHandlerResponseErrorHandlerClassifies HTTP errors as transient/non-transient

Exception Types

ExceptionBehaviorUse Case
TransientAiExceptionTriggers retryServer errors (5xx), rate limits, network errors
NonTransientAiExceptionFails immediatelyAuth errors (401, 403), bad requests (400)

HTTP Error Classification

Priority order for error handling:

  1. onHttpCodes (highest) → Retry
  2. excludeOnHttpCodes → No retry
  3. onClientErrors setting → Retry 4xx if true
  4. Default → Retry 5xx, no retry 4xx

Quick Reference

Default Configuration

PropertyDefaultDescription
max-attempts10Total retry attempts
on-client-errorsfalseRetry 4xx errors
backoff.initial-interval2sFirst retry delay
backoff.multiplier5Exponential growth factor
backoff.max-interval3mMaximum retry delay

Common HTTP Status Codes

CodeDefault BehaviorTypical Use
400No retryBad request (invalid format)
401No retryAuthentication failure
403No retryAuthorization failure
429RetryRate limit exceeded
500RetryInternal server error
503RetryService unavailable

Retry Progression

With default settings (initial: 2s, multiplier: 5, max: 3m):

AttemptWait Time
12s
210s
350s
4+180s (capped)

Core APIs

RetryTemplate

// Execute with retry
<T> T execute(RetryCallback<T, ?> callback);

// Execute with recovery fallback
<T> T execute(RetryCallback<T, ?> callback, RecoveryCallback<T> recovery);

SpringAiRetryProperties

// Configuration prefix: "spring.ai.retry"
int getMaxAttempts();                    // Default: 10
boolean isOnClientErrors();              // Default: false
List<Integer> getOnHttpCodes();          // Default: []
List<Integer> getExcludeOnHttpCodes();   // Default: []
Backoff getBackoff();                    // Nested configuration

Exception Constructors

// Transient (retryable)
TransientAiException(String message);
TransientAiException(String message, Throwable cause);

// Non-transient (not retryable)
NonTransientAiException(String message);
NonTransientAiException(String message, Throwable cause);

Package Information

  • Group ID: org.springframework.ai
  • Artifact ID: spring-ai-autoconfigure-retry
  • Version: 1.1.2
  • License: Apache-2.0
  • Language: Java
  • Package Type: Maven

Documentation Structure

Guides

  • Quick Start Guide - Step-by-step getting started
  • Configuration Guide - Detailed configuration options

Examples

Reference

Key Features

  • Automatic Bean Configuration: RetryTemplate and ResponseErrorHandler auto-configured
  • Exponential Backoff: Configurable backoff with initial interval, multiplier, and max cap
  • Intelligent Error Classification: HTTP status codes classified as transient/non-transient
  • Property-Based Configuration: All retry behavior configurable via Spring Boot properties
  • WebFlux Support: Automatic WebClient exception handling when WebFlux on classpath
  • Custom Override: Easy override of auto-configured beans with @ConditionalOnMissingBean

Architecture

┌─────────────────────────────────────┐
│  Spring Boot Auto-Configuration    │
├─────────────────────────────────────┤
│  SpringAiRetryAutoConfiguration    │
│  ├─ retryTemplate bean             │
│  └─ responseErrorHandler bean      │
└─────────────────────────────────────┘
         ↓                    ↓
┌────────────────┐   ┌───────────────────┐
│  RetryTemplate │   │ ResponseErrorHandler│
│  - Max attempts│   │ - Error classification│
│  - Backoff     │   │ - HTTP status codes  │
│  - Listeners   │   │ - Exception throwing │
└────────────────┘   └───────────────────┘
         ↓                    ↓
┌─────────────────────────────────────┐
│  Exception Classification           │
│  ├─ TransientAiException (retry)   │
│  └─ NonTransientAiException (fail) │
└─────────────────────────────────────┘

Dependencies

Required:

  • spring-ai-retry - Core retry utilities
  • spring-boot-starter - Spring Boot core
  • Spring Retry framework - Retry logic

Optional:

  • Spring WebFlux - WebClient support

Common Integration Patterns

RestTemplate with Retry

@Bean
public RestTemplate aiRestTemplate(ResponseErrorHandler errorHandler) {
    RestTemplate template = new RestTemplate();
    template.setErrorHandler(errorHandler);
    return template;
}

@Service
public class AiService {
    public String call(RetryTemplate retry, RestTemplate rest) {
        return retry.execute(ctx -> rest.postForObject(url, request, String.class));
    }
}

WebClient with Retry

@Service
public class ReactiveAiService {
    public String call(RetryTemplate retry, WebClient client) {
        return retry.execute(ctx -> 
            client.post().bodyValue(request).retrieve()
                  .bodyToMono(String.class).block()
        );
    }
}

Custom Error Handling

try {
    return retryTemplate.execute(ctx -> callApi());
} catch (TransientAiException e) {
    // All retries exhausted
    return "Service temporarily unavailable";
} catch (NonTransientAiException e) {
    // Permanent failure
    return "Configuration error";
}

Environment-Specific Configuration

Development (fast failure):

spring.ai.retry.max-attempts=2
spring.ai.retry.backoff.initial-interval=100ms
spring.ai.retry.backoff.max-interval=500ms

Production (robust retry):

spring.ai.retry.max-attempts=10
spring.ai.retry.backoff.initial-interval=2s
spring.ai.retry.backoff.max-interval=3m
spring.ai.retry.on-http-codes=429,503
spring.ai.retry.exclude-on-http-codes=401,403

Next Steps

  1. Getting Started: Read the Quick Start Guide
  2. Configuration: Explore Configuration Options
  3. Examples: Review Real-World Scenarios
  4. Deep Dive: Check API Reference for complete details
tessl i tessl/maven-org-springframework-ai--spring-ai-autoconfigure-retry@1.1.1
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.springframework.ai/spring-ai-autoconfigure-retry@1.1.x