Spring Retry - Quick Reference

Full Reference: See advanced.md for RetryTemplate patterns, custom retry policies, retry listeners, stateful retry, async retry, and testing.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: spring-retry for comprehensive documentation.

Dependencies

<dependency>
    <groupId>org.springframework.retry</groupId>
    <artifactId>spring-retry</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-aspects</artifactId>
</dependency>

Enable Retry

@SpringBootApplication
@EnableRetry
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

@Retryable Annotation

Basic Usage

@Retryable(maxAttempts = 3)
public String callExternalApi(String endpoint) {
    return restClient.get(endpoint);
}

With Specific Exceptions

@Retryable(
    retryFor = {ServiceUnavailableException.class, TimeoutException.class},
    noRetryFor = {PaymentDeclinedException.class},
    maxAttempts = 5
)
public PaymentResult processPayment(PaymentRequest request) {
    return paymentGateway.charge(request);
}

With Backoff

@Retryable(
    maxAttempts = 4,
    backoff = @Backoff(
        delay = 1000,       // Initial delay: 1 second
        multiplier = 2,     // Exponential: 1s, 2s, 4s
        maxDelay = 10000    // Max delay: 10 seconds
    )
)
public void sendNotification(Notification notification) {
    notificationClient.send(notification);
}

@Recover
public void recoverNotification(Exception e, Notification notification) {
    log.error("Failed to send notification after retries: {}", notification.getId());
    deadLetterQueue.add(notification);
}

@Recover Method

@Service
public class UserService {

    @Retryable(retryFor = ServiceException.class, maxAttempts = 3)
    public User getUser(Long id) {
        return userClient.findById(id);
    }

    // Must have same return type
    // First parameter can be the exception
    @Recover
    public User recoverGetUser(ServiceException e, Long id) {
        log.warn("Falling back to cached user for id: {}", id);
        return userCache.get(id);
    }

    // Multiple recover methods for different exceptions
    @Recover
    public User recoverGetUserTimeout(TimeoutException e, Long id) {
        return User.unknown(id);
    }
}

Best Practices

Do	Don't
Use exponential backoff	Fixed rapid retries
Set max attempts limit	Retry indefinitely
Handle non-retryable exceptions	Retry business errors
Log retry attempts	Silent retries
Implement recovery fallback	Let retries fail silently

When NOT to Use This Skill

• Circuit breaker - Use spring-cloud-circuitbreaker or Resilience4j
• Message retry - Use Kafka retry topics or DLT
• Non-idempotent operations - Ensure idempotency first
• Business errors - Only retry transient failures

Anti-Patterns

Anti-Pattern	Problem	Solution
Retry indefinitely	Hangs forever	Set max attempts
Fixed rapid retry	Overwhelms service	Use exponential backoff
Retrying business errors	Wastes resources	Use noRetryFor
No recovery method	Silent failures	Implement @Recover

Quick Troubleshooting

Problem	Diagnostic	Fix
Retry not happening	Check @EnableRetry	Add to config class
@Recover not called	Check method signature	Match return type and params
Too many retries	Check maxAttempts	Reduce or add timeout
Backoff not working	Check annotation	Verify @Backoff config

Production Checklist

• Appropriate max attempts set
• Exponential backoff configured
• Max delay capped
• Non-retryable exceptions defined
• Recovery methods implemented
• Retry listeners for monitoring
• Metrics on retry counts

Reference Documentation

• Spring Retry Reference