API Reference

Complete API documentation for Spring AI Retry.

RetryUtils

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

public abstract class RetryUtils

Package: org.springframework.ai.retry

RetryUtils is an abstract utility class containing only static members. It cannot be instantiated and serves as a namespace for retry-related constants and configurations.

Class Characteristics:

• Cannot be instantiated (abstract class with private constructor)
• Thread-safe (all static members are immutable)
• No state management required
• All configurations are pre-built and ready to use

Static Fields

DEFAULT_RETRY_TEMPLATE

public static final RetryTemplate DEFAULT_RETRY_TEMPLATE

Production-ready retry template with exponential backoff strategy.

Type: org.springframework.retry.support.RetryTemplate

Configuration:

• Max Attempts: 10
• Retryable Exceptions: TransientAiException, ResourceAccessException
• Backoff: Exponential (2s initial, 5x multiplier, 180s max)
• Observability: RetryListener with logging (WARN level, includes stack trace)

Thread Safety: Thread-safe, can be shared across threads

SHORT_RETRY_TEMPLATE

public static final RetryTemplate SHORT_RETRY_TEMPLATE

Fast-failing retry template optimized for testing.

Type: org.springframework.retry.support.RetryTemplate

Configuration:

• Max Attempts: 10
• Retryable Exceptions: TransientAiException, ResourceAccessException
• Backoff: Fixed (100ms)
• Observability: RetryListener with logging (WARN level, no stack trace)

Thread Safety: Thread-safe, can be shared across threads

DEFAULT_RESPONSE_ERROR_HANDLER

public static final ResponseErrorHandler DEFAULT_RESPONSE_ERROR_HANDLER

HTTP error handler that categorizes errors into transient and non-transient.

Type: org.springframework.web.client.ResponseErrorHandler

Behavior:

• 4xx → NonTransientAiException (not retried)
• 5xx → TransientAiException (retried)

Thread Safety: Stateless and thread-safe

Exception Types

TransientAiException

Exception for transient failures that may succeed on retry.

public class TransientAiException extends RuntimeException

Package: org.springframework.ai.retry

Extends: java.lang.RuntimeException

Constructors

public TransientAiException(String message)

Creates a new transient exception with the specified message.

Parameters:

• message - The error message describing the transient failure

public TransientAiException(String message, Throwable cause)

Creates a new transient exception with the specified message and cause.

Parameters:

• message - The error message describing the transient failure
• cause - The underlying cause

Inherited Methods

public String getMessage()

Returns the detail message string.

Returns: The detail message

public Throwable getCause()

Returns the cause of this exception or null.

Returns: The cause or null

public StackTraceElement[] getStackTrace()

Returns an array of stack trace elements.

Returns: Stack trace array

NonTransientAiException

Exception for permanent failures that should not be retried.

public class NonTransientAiException extends RuntimeException

Package: org.springframework.ai.retry

Extends: java.lang.RuntimeException

Constructors

public NonTransientAiException(String message)

Creates a new non-transient exception with the specified message.

Parameters:

• message - The error message describing the permanent failure

public NonTransientAiException(String message, Throwable cause)

Creates a new non-transient exception with the specified message and cause.

Parameters:

• message - The error message describing the permanent failure
• cause - The underlying cause

Inherited Methods

public String getMessage()

Returns the detail message string.

Returns: The detail message

public Throwable getCause()

Returns the cause of this exception or null.

Returns: The cause or null

public StackTraceElement[] getStackTrace()

Returns an array of stack trace elements.

Returns: Stack trace array

ResponseErrorHandler

HTTP error handler interface and implementation.

Interface Definition

public interface ResponseErrorHandler

Package: org.springframework.web.client

Methods

boolean hasError(ClientHttpResponse response) throws IOException

Checks if the HTTP response has an error status code.

Parameters:

• response - The HTTP response to check

Returns: true if status code is 4xx or 5xx, false otherwise

Throws: IOException if an I/O error occurs

void handleError(ClientHttpResponse response) throws IOException

Handles HTTP errors by reading the response body and throwing appropriate exception.

Parameters:

• response - The HTTP response to handle

Throws:

• NonTransientAiException - For 4xx client errors
• TransientAiException - For 5xx server errors
• IOException - If an I/O error occurs

void handleError(URI url, HttpMethod method, ClientHttpResponse response) throws IOException

Handles HTTP errors with additional URL and method context.

Parameters:

• url - The request URI
• method - The HTTP method used
• response - The HTTP response to handle

Throws:

• NonTransientAiException - For 4xx client errors
• TransientAiException - For 5xx server errors
• IOException - If an I/O error occurs

External Types

RetryTemplate

public class RetryTemplate implements RetryOperations

Package: org.springframework.retry.support

Methods

public <T, E extends Throwable> T execute(RetryCallback<T, E> callback) throws E

Execute with retry logic.

Type Parameters:

• T - Return type
• E - Exception type

Parameters:

• callback - The retry callback

Returns: Result from callback

Throws: E if all retries exhausted

public <T, E extends Throwable> T execute(RetryCallback<T, E> callback, RecoveryCallback<T> recoveryCallback) throws E

Execute with retry logic and recovery callback.

Type Parameters:

• T - Return type
• E - Exception type

Parameters:

• callback - The retry callback
• recoveryCallback - Called after all retries exhausted

Returns: Result from callback or recovery

public void registerListener(RetryListener listener)

Register a listener for retry events.

Parameters:

• listener - The retry listener

public RetryPolicy getRetryPolicy()

Get the retry policy.

Returns: The retry policy

public void setRetryPolicy(RetryPolicy retryPolicy)

Set the retry policy.

Parameters:

• retryPolicy - The retry policy

public void setBackOffPolicy(BackOffPolicy backOffPolicy)

Set the backoff policy.

Parameters:

• backOffPolicy - The backoff policy

RetryCallback

@FunctionalInterface
public interface RetryCallback<T, E extends Throwable>

Package: org.springframework.retry

Methods

T doWithRetry(RetryContext context) throws E

Perform operation with retry context.

Parameters:

• context - The retry context

Returns: Operation result

Throws: E on failure

RecoveryCallback

@FunctionalInterface
public interface RecoveryCallback<T>

Package: org.springframework.retry

Methods

T recover(RetryContext context) throws Exception

Perform recovery operation.

Parameters:

• context - The retry context

Returns: Recovery result

Throws: Exception on failure

RetryContext

public interface RetryContext

Package: org.springframework.retry

Methods

int getRetryCount()

Get the current retry count (0-based).

Returns: Current retry count

Throwable getLastThrowable()

Get the last exception that caused retry.

Returns: Last exception or null

String getName()

Get the name of this context.

Returns: Context name

boolean hasAttribute(String key)

Check if context has attribute.

Parameters:

• key - Attribute key

Returns: true if attribute exists

Object getAttribute(String key)

Get attribute value.

Parameters:

• key - Attribute key

Returns: Attribute value or null

ClientHttpResponse

public interface ClientHttpResponse extends HttpInputMessage, Closeable

Package: org.springframework.http.client

Methods

HttpStatusCode getStatusCode() throws IOException

Get the HTTP status code.

Returns: Status code

Throws: IOException on error

String getStatusText() throws IOException

Get the HTTP status text.

Returns: Status text

Throws: IOException on error

HttpHeaders getHeaders()

Get the response headers.

Returns: HTTP headers

InputStream getBody() throws IOException

Get the response body as input stream.

Returns: Body input stream

Throws: IOException on error

void close()

Close this response.

ResourceAccessException

public class ResourceAccessException extends RestClientException

Package: org.springframework.web.client

Exception for I/O errors during HTTP communication.

Constructors

public ResourceAccessException(String msg)

Create with message.

Parameters:

• msg - Error message

public ResourceAccessException(String msg, Throwable cause)

Create with message and cause.

Parameters:

• msg - Error message
• cause - Underlying cause

WebClientRequestException

public class WebClientRequestException extends WebClientException

Package: org.springframework.web.reactive.function.client

Only available when spring-webflux is on the classpath. Automatically added to retry list by auto-configuration.

Constructors

public WebClientRequestException(Throwable cause, HttpMethod method, URI uri, HttpHeaders headers)

Create with cause, method, URI, and headers.

Parameters:

• cause - Underlying cause
• method - HTTP method
• uri - Request URI
• headers - Request headers

Methods

public HttpMethod getMethod()

Get HTTP method.

Returns: HTTP method

public URI getUri()

Get request URI.

Returns: Request URI

public HttpHeaders getHeaders()

Get request headers.

Returns: Request headers

Next Steps

• Configuration Reference - Complete configuration documentation
• Exception Reference - Exception types and classification
• Type Reference - External types and dependencies