Error Handling & Fallbacks
Implement custom error handling and define fallback mechanisms for graceful degradation when services are unavailable.
Error Handling & Fallbacks is a free API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Resilient Error Handling Intro
In a microservices architecture, services can fail. An API Gateway needs robust error handling and fallback mechanisms to ensure the entire system remains stable and user-friendly.
This lesson explores how Spring Cloud Gateway helps you gracefully handle errors and provide alternative responses when backend services are unavailable.
Default Gateway Errors
By default, Spring Cloud Gateway provides generic error responses when a routed service is unreachable or returns an error. These often include standard HTTP status codes (like 500 Internal Server Error, 503 Service Unavailable) and basic JSON.
While functional, these default messages are usually not user-friendly and might expose internal details. Customization is key for a good user experience.
Customizing Error Responses
To improve user experience, we can customize the error responses from the Gateway. This allows us to:
- Provide clear, branded error messages.
- Hide sensitive internal error details.
- Return consistent error formats across all APIs.
Spring Cloud Gateway, being built on Spring WebFlux, allows us to implement custom ErrorWebExceptionHandler components.
Custom Error Handler Example
Let's create a custom error handler that intercepts errors and returns a simplified JSON response. This handler will replace the default error page.
Run this code and try accessing /fail. You'll see our custom message!
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.route.builder.RouteLocatorBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.boot.web.reactive.error.ErrorWebExceptionHandler;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.server.reactive.ServerHttpResponse;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;
import java.nio.charset.StandardCharsets;
@SpringBootApplication
public class GatewayApplication {
public static void main(String[] args) {
SpringApplication.run(GatewayApplication.class, args);
}
@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
return builder.routes()
.route("nonexistent_service", r -> r.path("/fail/**")
.uri("http://localhost:9999")) // Route to a non-existent service
.build();
}
}
@Configuration
@Order(-1) // Ensure this handler runs before default ones
class CustomJsonErrorWebExceptionHandler implements ErrorWebExceptionHandler {
@Override
public Mono<Void> handle(ServerWebExchange exchange, Throwable ex) {
ServerHttpResponse response = exchange.getResponse();
response.setStatusCode(HttpStatus.INTERNAL_SERVER_ERROR);
response.getHeaders().setContentType(MediaType.APPLICATION_JSON);
String errorBody = "{\"status\":500, \"message\":\"Our service is temporarily unavailable. Please try again!\"}";
DataBuffer buffer = response.bufferFactory().wrap(errorBody.getBytes(StandardCharsets.UTF_8));
return response.writeWith(Mono.just(buffer));
}
}Understanding Fallback Mechanisms
A fallback mechanism provides an alternative path or response when a primary service fails or becomes unavailable. Instead of showing a raw error, the Gateway can gracefully degrade by:
- Returning a default response.
- Redirecting to a static error page.
- Calling a dedicated fallback service.
Fallbacks are crucial for resilience and preventing cascading failures.
Gateway Fallback Strategies
Spring Cloud Gateway supports fallbacks primarily through its integration with circuit breakers (like Resilience4j, which we discussed in the previous lesson). When a circuit breaker trips, instead of failing outright, it can invoke a fallback.
A common way to define this fallback is using the setFallbackUri() method within the circuit breaker filter, often pointing to a forward: URI.
Implementing a Simple Fallback Route
The simplest fallback is to forward the request to another URI within the Gateway itself. This can be a static HTML page, a simple Spring controller method, or even another internal route.
The forward: prefix in fallbackUri tells the Gateway to handle the request internally, without making another external HTTP call.
Configuring a Fallback Route
Here's how to configure a route with a fallback. If the /api/** route's backend service fails (e.g., due to a circuit breaker opening), the Gateway will forward the request to our local /fallback endpoint.
Try accessing /api/hello when localhost:9000 is down.
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.route.builder.RouteLocatorBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
@RestController // For our simple fallback endpoint
public class GatewayApplication {
public static void main(String[] args) {
SpringApplication.run(GatewayApplication.class, args);
}
@Bean
public RouteLocator routes(RouteLocatorBuilder builder) {
return builder.routes()
.route("backend_service", r -> r.path("/api/**")
.filters(f -> f.circuitBreaker(config -> config
.setName("myCircuitBreaker")
.setFallbackUri("forward:/fallback"))) // Fallback URI
.uri("http://localhost:9000")) // A service that might fail
.build();
}
// This method acts as the fallback service
@GetMapping("/fallback")
public String fallback() {
return "Service is currently unavailable. Please try again later!";
}
}Fallback to a Dedicated Service
For more complex scenarios, you might configure fallbackUri to point to a dedicated microservice. This "fallback service" can:
- Serve rich error pages.
- Provide cached or default data.
- Log detailed error information.
This approach centralizes error handling logic and keeps your Gateway configuration cleaner.
Check Your Knowledge
Which of the following are benefits of implementing custom error handling and fallback mechanisms in an API Gateway?
Lesson Summary
In this lesson, we learned the importance of robust error handling and fallback mechanisms in Spring Cloud Gateway. We explored how to:
- Customize default error responses using
ErrorWebExceptionHandler. - Implement simple fallbacks using
setFallbackUri("forward:")with circuit breakers. - Understand the benefits of dedicated fallback services for advanced scenarios.
These techniques are vital for building resilient and user-friendly microservice applications.
Frequently asked questions
Is the “Error Handling & Fallbacks” lesson free?
Yes — the full text of “Error Handling & Fallbacks” is free to read here on the web, and the API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) course, upgrade to CoddyKit PRO.
What will I learn in “Error Handling & Fallbacks”?
Implement custom error handling and define fallback mechanisms for graceful degradation when services are unavailable. You practise API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway)?
No prior experience is required. API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Error Handling & Fallbacks” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) lesson?
Yes. Every API Gateway & Reverse Proxy (Nginx + Spring Cloud Gateway) lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.