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

Spring AI utility library providing retry mechanisms for AI API interactions with comprehensive error handling and exception classification

Overview

Eval results

Files

Configuration Guide

Name: tessl/maven-org-springframework-ai--spring-ai-retry
Author: tessl

This guide covers all configuration options and scenarios for Spring AI Retry.

Configuration Methods

Method 1: Static Constants

Use pre-configured constants from RetryUtils:

import org.springframework.ai.retry.RetryUtils;

// Production configuration (10 attempts, exponential backoff)
RetryTemplate template = RetryUtils.DEFAULT_RETRY_TEMPLATE;

// Testing configuration (10 attempts, fixed 100ms backoff)
RetryTemplate testTemplate = RetryUtils.SHORT_RETRY_TEMPLATE;

// Error handler (4xx → non-transient, 5xx → transient)
ResponseErrorHandler errorHandler = RetryUtils.DEFAULT_RESPONSE_ERROR_HANDLER;

Method 2: Spring Boot Properties

Configure via application.yml or application.properties:

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

Method 3: Custom RetryTemplate

Build your own configuration:

import org.springframework.ai.retry.TransientAiException;
import org.springframework.retry.support.RetryTemplate;
import org.springframework.web.client.ResourceAccessException;
import java.time.Duration;

RetryTemplate customTemplate = RetryTemplate.builder()
    .maxAttempts(5)
    .retryOn(TransientAiException.class)
    .retryOn(ResourceAccessException.class)
    .exponentialBackoff(
        Duration.ofMillis(1000),  // initial interval
        2.0,                       // multiplier
        Duration.ofMillis(30000)   // max interval
    )
    .build();

Configuration Properties Reference

spring.ai.retry.max-attempts

Maximum number of retry attempts.

Type: integer
Default: 10
Valid Range: 1 to Integer.MAX_VALUE (practical: 1-100)

spring.ai.retry.max-attempts: 5

spring.ai.retry.on-client-errors

Controls whether 4xx client errors should be retried.

Type: boolean
Default: false
Values:
- false - 4xx errors are non-transient (not retried)
- true - 4xx errors are transient (retried)

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

spring.ai.retry.on-http-codes

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

Type: list of integers
Default: empty list
Priority: Evaluated first
Common Values: [429, 503, 504]

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

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

HTTP status codes that should never be retried.

Type: list of integers
Default: empty list
Priority: Evaluated third (after onHttpCodes and onClientErrors)
Common Values: [401, 403, 404]

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

spring.ai.retry.backoff.initial-interval

Initial delay before first retry.

Type: duration
Default: 2000ms (2 seconds)
Formats: 1000ms, 1s, PT1S
Valid Range: 0ms to Long.MAX_VALUE (practical: 100ms to 10s)

spring.ai.retry.backoff.initial-interval: 1000ms

spring.ai.retry.backoff.multiplier

Multiplier applied to each subsequent retry delay.

Type: integer
Default: 5
Valid Range: 1 to Integer.MAX_VALUE (practical: 1-10)
Common Values:
- 2 - Gentle exponential growth
- 3 - Moderate growth
- 5 - Aggressive growth (default)
- 10 - Very aggressive growth

spring.ai.retry.backoff.multiplier: 2

spring.ai.retry.backoff.max-interval

Maximum backoff duration (cap for exponential growth).

Type: duration
Default: 180000ms (3 minutes)
Formats: 30000ms, 30s, PT30S
Must Be: >= initial-interval

spring.ai.retry.backoff.max-interval: 30000ms

Configuration Scenarios

Scenario 1: Conservative Retry (Minimize Costs)

Minimize retry attempts and costs while handling genuine transient failures.

spring:
  ai:
    retry:
      max-attempts: 3
      on-client-errors: false
      on-http-codes: [503, 504]  # Only retry clear service issues
      exclude-on-http-codes: [429]  # Don't retry rate limits
      backoff:
        initial-interval: 500ms
        multiplier: 2
        max-interval: 5000ms

Use Case: Cost-sensitive applications, development environments

Behavior:

Only 3 attempts (fast failure)
Only retries 503/504 (clear service outages)
Rate limits (429) fail immediately
Short backoff (max 5 seconds)
Total max time: ~5.5 seconds

Scenario 2: Aggressive Retry (Maximize Success)

Maximize success rate with extensive retry attempts and long backoff.

spring:
  ai:
    retry:
      max-attempts: 15
      on-client-errors: false
      on-http-codes: [429, 503, 504]
      exclude-on-http-codes: [401, 403, 404]
      backoff:
        initial-interval: 5000ms
        multiplier: 3
        max-interval: 300000ms  # 5 minutes

Use Case: Critical production systems, high-value requests

Behavior:

15 attempts (very persistent)
Retries rate limits (429)
Long backoff (up to 5 minutes)
Never retries auth errors
Total max time: up to 1 hour+

Scenario 3: Fast Testing

Optimize for fast test execution while maintaining retry logic.

spring:
  ai:
    retry:
      max-attempts: 3
      on-client-errors: false
      on-http-codes: [503]
      backoff:
        initial-interval: 10ms
        multiplier: 2
        max-interval: 100ms

Use Case: Unit tests, integration tests

Behavior:

Only 3 attempts
Very short delays (10ms, 20ms, 40ms)
Total max time: ~70ms
Tests complete quickly

Scenario 4: Rate Limit Friendly

Handle rate limits gracefully with appropriate backoff.

spring:
  ai:
    retry:
      max-attempts: 10
      on-client-errors: false
      on-http-codes: [429, 503, 504]
      backoff:
        initial-interval: 10000ms  # 10 seconds
        multiplier: 1  # Fixed backoff
        max-interval: 10000ms

Use Case: Applications hitting rate limits frequently

Behavior:

Always retries 429 (rate limit)
Fixed 10-second delay (matches typical rate limit windows)
10 attempts = up to 100 seconds of waiting
Prevents overwhelming rate-limited service

Scenario 5: Multi-Region Failover

Quick failure to allow failover to alternate regions/providers.

spring:
  ai:
    retry:
      max-attempts: 2
      on-client-errors: false
      on-http-codes: []
      backoff:
        initial-interval: 100ms
        multiplier: 2
        max-interval: 500ms

Use Case: Multi-provider or multi-region architectures

Behavior:

Only 2 attempts per provider
Fast failure (max 600ms total)
Application can try next provider quickly
Reduces latency in multi-provider scenarios

Error Classification Priority

The auto-configured error handler evaluates HTTP errors in this order:

onHttpCodes match → TransientAiException (retried)
4xx + onClientErrors=false → NonTransientAiException (not retried)
excludeOnHttpCodes match → NonTransientAiException (not retried)
Default → TransientAiException (retried)

Example

spring.ai.retry:
  on-client-errors: false
  on-http-codes: [429, 503, 504]
  exclude-on-http-codes: [401, 403]

HTTP Code	Result	Reason
429	TransientAiException	In onHttpCodes (priority 1)
400	NonTransientAiException	4xx + onClientErrors=false (priority 2)
401	NonTransientAiException	In excludeOnHttpCodes (priority 3)
500	TransientAiException	Default (priority 4)

Backoff Calculation

Exponential Backoff

With initial-interval: 2s, multiplier: 5, max-interval: 180s:

Attempt	Calculation	Delay	Cumulative
1	-	0s	0s
2	2s × 1	2s	2s
3	2s × 5	10s	12s
4	10s × 5	50s	62s
5	50s × 5 = 250s → cap	180s	242s
6-10	capped	180s each	up to 1142s

Fixed Backoff

Set multiplier: 1 for fixed delays:

backoff:
  initial-interval: 5s
  multiplier: 1
  max-interval: 5s

Results in: 5s, 5s, 5s, 5s... (all attempts same delay)

Custom Configuration Bean

Override auto-configuration with custom beans:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.retry.support.RetryTemplate;
import org.springframework.web.client.ResponseErrorHandler;

@Configuration
public class CustomRetryConfig {
    
    @Bean
    public RetryTemplate retryTemplate() {
        // Your custom RetryTemplate takes precedence
        return RetryTemplate.builder()
            .maxAttempts(3)
            .fixedBackoff(1000)
            .retryOn(TransientAiException.class)
            .build();
    }
    
    @Bean
    public ResponseErrorHandler responseErrorHandler() {
        // Your custom error handler takes precedence
        return new CustomAiErrorHandler();
    }
}

Disabling Auto-Configuration

To disable auto-configuration entirely:

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

Or via annotation:

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

Environment-Specific Configuration

Development

spring:
  profiles: dev
  ai:
    retry:
      max-attempts: 2  # Fail fast in dev
      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

Comparison: Static vs Auto-Configuration

Feature	RetryUtils Constants	Auto-Configuration
Configuration Method	Hardcoded	Property-based
Max Attempts	Fixed: 10	Configurable
Backoff	Fixed: 2s → 180s	Fully configurable
4xx Handling	Always non-transient	Configurable
HTTP Code Lists	Not supported	Supported
WebFlux Support	No	Automatic
Bean Override	Manual	Automatic
Best For	Simple apps, testing	Production Spring Boot

Next Steps

Quick Start Guide - Get started with basic setup
Integration Patterns - See real-world configurations in action
Configuration Reference - Complete property documentation

Install with Tessl CLI

npx tessl i tessl/maven-org-springframework-ai--spring-ai-retry

docs

examples

guides

configuration-guide.md

quick-start.md

reference

index.md

tile.json

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