Returning Errors Using ProblemDetail in Spring Boot

In a Spring Boot application, error handling is an important aspect of providing a robust and user-friendly API. Traditionally, Spring Boot has provided various methods like @ExceptionHandler, ResponseEntityExceptionHandler, and @ControllerAdvice for handling exceptions.

With Spring Framework 6 and Spring Boot 3, a new way to standardize error responses was introduced i.e. ProblemDetail. ProblemDetail is based on RFC 7807 (Problem Details for HTTP APIs), which defines a standardized structure for providing machine-readable error responses. This approach makes it easier for clients to parse and understand errors.

Prerequisites:

• Basic knowledge of the Java and Spring Boot.
• Maven for building dependency management.
• JDK and IntelliJ IDEA installed in your system.

ProblemDetail in Spring Boot

The ProblemDetail class in Spring Boot is based on the RFC 7807 specification, which defines the standard way to represent error responses in HTTP APIs. This specification, commonly known as Problem Details for HTTP APIs, provides a standardized format for conveying error information to clients, making error handling more consistent and easier to parse.

What is ProblemDetail?

ProblemDetail is a data structure that encapsulates details about the error or problem encountered by the HTTP request. It allows developers to represent error messages in a uniform way, making it easier for clients (like frontend applications or other services) to interpret and act upon the error information.

Prior to ProblemDetail, developers often created custom error response structures, leading to inconsistent error formats across different services or APIs. With ProblemDetail, Spring Boot standardizes how error information is shared, aligning with modern practices in RESTful APIs.

Structure of ProblemDetail

ProblemDetail uses a JSON-based structure that consists of several fields:

• type: The URI reference that identifies the type of the problem. This is the link that clients can follow to get more information about the specific error type. For example, if a user tries to access a resource that doesn't exist, the type could point to a URL like https://example.com/not-found, where documentation for the error can be found.
• title: A short, human-readable summary of the problem. This is meant for display and should give a brief overview of the error.
• status: The HTTP status code generated by the problem, such as 404 for "Not Found" or 400 for "Bad Request." This helps clients quickly understand the nature of the problem without needing to parse the entire response.
• detail: The human-readable explanation specific to this occurrence of the problem. It provides more detailed information about the error, often including dynamic content like IDs or parameters related to the error.
• instance: The URI reference that identifies the specific occurrence of the problem. This typically points to the particular request or entity that caused the issue, allowing the client to trace back to the request context.

Example ProblemDetail JSON Response

Here’s an example of what a ProblemDetail response might look like when the client requests a non-existent resource:

{
    "type": "https://example.com/not-found",
    "title": "Resource Not Found",
    "status": 404,
    "detail": "Resource with ID 42 not found",
    "instance": "/resource/42"
}

• The type field (https://example.com/not-found) could link to the page that explains what the "Resource Not Found" error means.
• The title ("Resource Not Found") provides a brief description of the error.
• The status (404) indicates to the client that this is an HTTP 404 error.
• The detail ("Resource with ID 42 not found") offers specific information about the problem.
• The instance (/resource/42) points to the endpoint that triggered the error.

Why Use ProblemDetail?

• Consistency: Using ProblemDetail allows you to standardize error messages across different APIs and services, making it easier for clients to handle errors uniformly.
• Clarity: By providing a structured error response, we make API behavior more predictable. Clients can use the type and status fields to categorize and handle errors programmatically.
• Self-documentation: The type field allows linking to documentation pages or resources that explain the error, providing the self-documenting nature of the API. This helps clients understand the issue and find potential solutions without needing additional support.
• Ease of Parsing: Frontend applications or other services can use the fields of ProblemDetail to prevent error messages or implement retries, as they can directly interpret the status code and type.

Project Implementation to Return Errors Using ProblemDetail in Spring Boot

This example project will guide you through the creation of a Spring Boot project that uses ProblemDetail for error handling. It includes the file structure, code implementation, and explanations for each part of the project.

Step 1: Create a New Spring Boot Project

Create a new Spring Boot project using IntelliJ IDEA. Choose the following options:

• Name: spring-boot-problemdetail-example
• Language: Java
• Type: Maven
• Packaging: Jar
• Click on the Next button.

Step 2: Add the Dependencies

Add the following dependencies into the Spring Boot project.

• Spring Web
• Spring Boot DevTools
• Lombok

Click on the Create button.

Project Structure

After the project creation done, set the folder structure as shown in the below image:

Step 3: Configure Application Properties

Open application.properties and add the following configuration to the Spring Boot project:

spring.application.name=spring-boot-problemdetail-example
server.port=8080

Step 4: Define a Custom Exception (ResourceNotFoundException.java)

Create a custom exception to represent the resource not found scenario in your Spring Boot project.

package com.gfg.springbootproblemdetailexample.exception;

// Custom exception for resource not found scenarios
public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) {
        super(message); // Pass the error message to the superclass
    }
}

Step 5: Create the Global Exception Handler (GlobalExceptionHandler.java)

Create the GlobalExceptionHandler class to handle exceptions globally using @ControllerAdvice and @ExceptionHandler with ProblemDetail.

package com.gfg.springbootproblemdetailexample.exception;

import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;

import java.net.URI;

// Global exception handler for managing ResourceNotFoundException
@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class) // Handle ResourceNotFoundException
    @ResponseStatus(HttpStatus.NOT_FOUND) // Set response status to 404
    public ProblemDetail handleResourceNotFoundException(ResourceNotFoundException ex) {
        // Create ProblemDetail object for the error response
        ProblemDetail problemDetail = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);
        problemDetail.setTitle("Resource Not Found"); // Set title of the error
        problemDetail.setDetail(ex.getMessage()); // Set detailed error message
        problemDetail.setInstance(URI.create("/resource/not-found")); // Set URI of the error instance
        problemDetail.setType(URI.create("https://example.com/not-found")); // Set type link for further information
        return problemDetail; // Return the ProblemDetail response
    }
}

• Catches the ResourceNotFoundException.
• Sets the HTTP status to 404.
• Creates the ProblemDetail object, providing details like title, status, detail, type, and instance.
• Returns the ProblemDetail response to the client.

Step 6: Create a Sample Controller (SampleController.java)

Create the SampleController class, which will have the endpoint that simulates the error.

package com.gfg.springbootproblemdetailexample.controller;

import com.gfg.springbootproblemdetailexample.exception.ResourceNotFoundException;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

// Controller for handling resource requests
@RestController
public class SampleController {

    @GetMapping("/resource/{id}") // Endpoint to get resource by ID
    public String getResource(@PathVariable("id") int id) {
        if (id != 1) { // Simulate resource not found for IDs other than 1
            throw new ResourceNotFoundException("Resource with ID " + id + " not found");
        }
        return "Resource found"; // Return success message for valid ID
    }
}

Step 7: Main Application Class (SpringBootProblemdetailExampleApplication.java)

This class contains the main method to run the Spring Boot application.

package com.gfg.springbootproblemdetailexample;

// Main application class for Spring Boot
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

// Spring Boot application entry point
@SpringBootApplication
public class SpringBootProblemdetailExampleApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringBootProblemdetailExampleApplication.class, args); // Run the application
    }
}

pom.xml File:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.4</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.gfg</groupId>
    <artifactId>spring-boot-problemdetail-example</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>spring-boot-problemdetail-example</name>
    <description>spring-boot-problemdetail-example</description>
    <url/>
    <licenses>
        <license/>
    </licenses>
    <developers>
        <developer/>
    </developers>
    <scm>
        <connection/>
        <developerConnection/>
        <tag/>
        <url/>
    </scm>
    <properties>
        <java.version>17</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

Step 8: Run the Application

To run the application, execute the SpringBootProblemdetailExampleApplication class in your IDE or use the command line:

mvn spring-boot:run

Output:

Step 10: Testing the Application

We can use the Postman tool to test the endpoint.

GET http://localhost:8080/resource/2

Invalid Request: GET /resource/2

Response:

When you request GET /resource/2, the response will be:

Note: For Valid Request i.e. GET /resource/1, Response will be "Resource found"

This example project demonstrates how to use the ProblemDetail for standardized error handling in the Spring Boot application. By implementing the custom exception, the global exception handler, and returning the well-structured ProblemDetail response, we can provide clients with the consistent and machine-readable error format.