Spring RestTemplate Error Handling: ResponseErrorHandler and Custom Strategies

Every Spring developer I've mentored starts with RestTemplate like it's a magic wand. They write a few getForObject() calls, everything works in dev, and then production hits them with a 502 Bad Gateway at 3 AM. The default ResponseErrorHandler is the silent killer — it throws a generic HttpClientErrorException with a message like "400 Bad Request" and no response body. Good luck debugging that.

I've seen teams waste days tracking down why a downstream service returned a 409 Conflict, only to realize the default handler swallowed the error details. In one particularly painful incident at a payments startup, our entire transaction pipeline stalled because we couldn't differentiate a 402 Payment Required from a 500 Internal Server Error.

Here's the hard truth: the default error handling in RestTemplate is designed for simplicity, not production resilience. If you're building anything beyond a toy app, you need a custom ResponseErrorHandler. This article covers everything I've learned from 15+ years of Spring development — from basic custom handlers to advanced strategies that handle retries, fallbacks, and circuit breakers.

We'll start with the default behavior, then build up to production-grade error handling. By the end, you'll know exactly how to handle every HTTP status code your downstream services can throw at you.

Understanding the Default ResponseErrorHandler

Let's start with what you get out of the box. Spring's DefaultResponseErrorHandler is the default implementation used by RestTemplate. Its hasError() method considers any HTTP status in the 4xx or 5xx range as an error. The handleError() method reads the response body (if available) and throws either HttpClientErrorException for 4xx or HttpServerErrorException for 5xx.

Here's the kicker: the default handler does include the response body in the exception's responseBody field, but it's often not exposed in the error message. When you catch the exception and call getMessage(), you get something like "400 Bad Request" — no body. You have to explicitly call getResponseBodyAsString() to get the details. I've seen countless developers miss this and assume the body was lost.

But there's a bigger problem: the default handler treats all 4xx errors uniformly. A 400 Bad Request from a validation error is handled the same as a 404 Not Found. In a microservices architecture, you need to differentiate between these to implement proper retry logic or fallbacks.

Another gotcha: the default handler only considers status codes. It doesn't look at response headers or content type. If your API returns a 200 OK with an error JSON body (a common anti-pattern), the default handler won't catch it. You'd need to override hasError() to inspect the body.

// Default behavior - RestTemplate automatically uses DefaultResponseErrorHandler
RestTemplate restTemplate = new RestTemplate();

try {
    String result = restTemplate.getForObject("https://api.example.com/users/999", String.class);
} catch (HttpClientErrorException e) {
    System.out.println("Status code: " + e.getStatusCode());
    System.out.println("Response body: " + e.getResponseBodyAsString()); // Don't forget this!
    System.out.println("Message: " + e.getMessage()); // Only shows status code
}

Implementing a Custom ResponseErrorHandler

Now let's build a custom handler that actually helps you sleep at night. The key is to map HTTP status codes to your application's domain exceptions. This way, your service layer can catch a UserNotFoundException instead of a generic HttpClientErrorException.

Here's my battle-tested approach: create a RestTemplateErrorHandler class that implements ResponseErrorHandler. Override hasError() to include any status you consider an error — maybe even 3xx redirects if you want to treat them as errors. Override handleError() to read the response body and throw a domain-specific exception based on the status code.

I always include a fallback that throws a generic RestClientException for unexpected status codes. This prevents unhandled statuses from causing confusing NullPointerExceptions downstream.

One pattern I've seen fail: teams put too much logic in the error handler, like retry or fallback calls. Don't do that. The error handler's job is to translate the HTTP response into an exception. Let the caller decide how to retry or fallback. Keep it single-responsibility.

public class CustomResponseErrorHandler implements ResponseErrorHandler {

    private static final Logger log = LoggerFactory.getLogger(CustomResponseErrorHandler.class);

    @Override
    public boolean hasError(ClientHttpResponse response) throws IOException {
        // Treat 4xx and 5xx as errors, plus optionally 3xx redirects
        HttpStatus statusCode = response.getStatusCode();
        return statusCode.is4xxClientError() || statusCode.is5xxServerError();
    }

    @Override
    public void handleError(ClientHttpResponse response) throws IOException {
        String body = new String(StreamUtils.copyToByteArray(response.getBody()), StandardCharsets.UTF_8);
        HttpStatus statusCode = response.getStatusCode();
        
        log.error("HTTP {} {} - Response body: {}", statusCode.value(), statusCode.getReasonPhrase(), body);
        
        switch (statusCode) {
            case BAD_REQUEST:
                throw new ValidationException(body);
            case NOT_FOUND:
                throw new ResourceNotFoundException(body);
            case CONFLICT:
                throw new ConflictException(body);
            case INTERNAL_SERVER_ERROR:
                throw new DownstreamServiceException(body);
            default:
                throw new RestClientException("Unexpected status code " + statusCode + ": " + body);
        }
    }
}

// Usage
RestTemplate restTemplate = new RestTemplate();
restTemplate.setErrorHandler(new CustomResponseErrorHandler());

Advanced Strategies: Retry, Fallback, and Circuit Breakers

Once you have a custom error handler, you need to decide what happens after the exception is thrown. In a microservices environment, you can't just let every 5xx error propagate to the user. You need retries with exponential backoff, fallback responses, and circuit breakers.

Here's the pattern I use: annotate your service method with Spring Retry's @Retryable. Configure it to retry on HttpServerErrorException (5xx) but not on HttpClientErrorException (4xx) because retrying a bad request is pointless. Use @Recover to define a fallback method that returns a cached response or a default value.

For circuit breakers, I use Resilience4j (Spring Cloud Circuit Breaker). The CircuitBreakerFactory wraps your RestTemplate call and opens the circuit when error rate exceeds a threshold. This prevents cascading failures.

But here's the nuance: your error handler must rethrow exceptions for the retry mechanism to work. If you catch the exception inside the handler and return a default value, the retry won't trigger. Always let the exception propagate up to the retry-aware layer.

@Service
public class PaymentService {

    private final RestTemplate restTemplate;

    public PaymentService(RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
        restTemplate.setErrorHandler(new CustomResponseErrorHandler());
    }

    @Retryable(
        value = {DownstreamServiceException.class},
        maxAttempts = 3,
        backoff = @Backoff(delay = 1000, multiplier = 2)
    )
    public PaymentResponse processPayment(PaymentRequest request) {
        return restTemplate.postForObject(
            "https://payment-gateway/api/payments",
            request,
            PaymentResponse.class
        );
    }

    @Recover
    public PaymentResponse recover(DownstreamServiceException e, PaymentRequest request) {
        // Fallback: return cached response or default
        log.warn("Payment processing failed after retries, returning fallback", e);
        return new PaymentResponse("PENDING", "Payment queued for manual review");
    }
}

What the Official Docs Won't Tell You

The official Spring documentation covers the basics of ResponseErrorHandler, but there are several gotchas that only experience teaches you.

1. The hasError() method is called before handleError(). If hasError() returns false, handleError() is never invoked. This means if you want to handle a 3xx redirect as an error, you must override hasError() to return true for those statuses. I once saw a team wondering why their error handler never fired for 302 responses — they only overrode handleError().

2. The response body stream can only be read once. After handleError() reads the body, subsequent reads will return empty. If you have a logging filter that also reads the body, you'll get an empty stream in your handler. Solution: use org.springframework.util.StreamUtils and wrap the body in a BufferedInputStream or read it early.

**3. The default handler throws HttpClientErrorException even for 5xx errors if the status code is in the 4xx range? No, that's not true. But there's a subtle bug: if your server returns a 4xx status with a malformed response body (e.g., invalid JSON), the default handler will throw an UnknownHttpStatusCodeException because it can't parse the status code. This is rare but happens.

4. RestTemplate's exchange() method doesn't use the error handler if the response type is ResponseEntity. Wait, that's not true either. Actually, the error handler is always used. But there's a nuance: if you use exchange() and the response body is empty (e.g., 204 No Content), the error handler might not be called because hasError() returns false for 2xx. So you're safe.

5. The error handler is not used for execute() calls with a custom ResponseExtractor. This is true. If you use RestTemplate.execute() with a ResponseExtractor, you have to handle errors yourself inside the extractor. The error handler is bypassed. Always use exchange() or the convenience methods like getForObject() for automatic error handling.

// Problem: reading body twice
@Override
public void handleError(ClientHttpResponse response) throws IOException {
    // First read - works
    String body1 = new String(StreamUtils.copyToByteArray(response.getBody()));
    // Second read - empty!
    String body2 = new String(StreamUtils.copyToByteArray(response.getBody()));
    // body2 is empty because the stream is exhausted
}

// Solution: wrap or read once
public class SafeResponseErrorHandler implements ResponseErrorHandler {
    @Override
    public void handleError(ClientHttpResponse response) throws IOException {
        byte[] bodyBytes = StreamUtils.copyToByteArray(response.getBody());
        String body = new String(bodyBytes, StandardCharsets.UTF_8);
        // Now use body as needed, don't read again
        log.error("Error response: {}", body);
        // ... throw exception
    }
}

Testing Your Error Handler with MockRestServiceServer

You can't claim production readiness without testing your error handling. Spring provides MockRestServiceServer for mocking RestTemplate calls. It's perfect for testing error scenarios.

Here's the pattern: create a MockRestServiceServer bound to your RestTemplate instance. Use expect().andRespond(withStatus(HttpStatus.NOT_FOUND).body("...")) to simulate error responses. Then call your service method and assert that the correct exception is thrown.

I always test the following scenarios: 400 with validation error, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 500 Internal Server Error, and 503 Service Unavailable. Each should throw the corresponding domain exception.

One common mistake: forgetting to set the error handler on the RestTemplate before binding the mock server. The mock server works by intercepting the request, so the error handler must be set beforehand.

Another gotcha: the mock server's response body is read as a String, but your error handler might expect a specific encoding. Always set the content type header in the mock response to match your production API.

@ExtendWith(MockitoExtension.class)
class PaymentServiceTest {

    private MockRestServiceServer mockServer;
    private PaymentService paymentService;

    @BeforeEach
    void setUp() {
        RestTemplate restTemplate = new RestTemplate();
        restTemplate.setErrorHandler(new CustomResponseErrorHandler());
        mockServer = MockRestServiceServer.bindTo(restTemplate).build();
        paymentService = new PaymentService(restTemplate);
    }

    @Test
    void testNotFoundThrowsResourceNotFoundException() {
        mockServer.expect(requestTo("/api/payments/123"))
            .andRespond(withStatus(HttpStatus.NOT_FOUND)
                .contentType(MediaType.APPLICATION_JSON)
                .body("{\"error\":\"Payment not found\"}"));

        assertThrows(ResourceNotFoundException.class, () -> {
            paymentService.getPayment("123");
        });

        mockServer.verify();
    }

    @Test
    void testServerErrorThrowsDownstreamServiceException() {
        mockServer.expect(requestTo("/api/payments"))
            .andRespond(withStatus(HttpStatus.INTERNAL_SERVER_ERROR)
                .body("{\"error\":\"Internal error\"}"));

        assertThrows(DownstreamServiceException.class, () -> {
            paymentService.processPayment(new PaymentRequest());
        });

        mockServer.verify();
    }
}

Error Handling with WebClient: The Modern Alternative

If you're starting a new project in 2024, you should consider WebClient over RestTemplate. Spring officially deprecated RestTemplate in favor of WebClient. But many legacy systems still use RestTemplate, and migrating isn't always feasible.

WebClient has a different error handling model. Instead of a global error handler, you use onStatus() to define error handling per request. This is more flexible but can lead to code duplication if you're not careful.

Here's my recommendation: if you're on Spring Boot 3.x and building new services, use WebClient. If you're maintaining an existing RestTemplate codebase, stick with it but improve the error handling. Don't mix both in the same service — I've seen teams do that and it's a maintenance nightmare.

For WebClient, you can create a shared ExchangeFilterFunction that centralizes error handling, similar to a custom ResponseErrorHandler. But that's a topic for another article.

// WebClient equivalent of custom error handling
WebClient webClient = WebClient.builder()
    .baseUrl("https://api.example.com")
    .filter(ExchangeFilterFunction.ofResponseProcessor(clientResponse -> {
        if (clientResponse.statusCode().isError()) {
            return clientResponse.bodyToMono(String.class)
                .flatMap(body -> {
                    log.error("Error response: {} {}", clientResponse.statusCode(), body);
                    if (clientResponse.statusCode() == HttpStatus.NOT_FOUND) {
                        return Mono.error(new ResourceNotFoundException(body));
                    }
                    return Mono.error(new DownstreamServiceException(body));
                });
        }
        return Mono.just(clientResponse);
    }))
    .build();