Creating Standardized API Error Responses in Spring Boot

Course: Advanced Java Training

Topic: Creating Standardized API Error Responses

Course Link: Advanced Java Training – JustAcademy

Demo Link: Register for a Course Demo

Official Website: JustAcademy

1. Introduction to Standardized API Error Responses

In modern Java applications, REST APIs are used to exchange data between clients and servers. During API execution, errors may occur because of invalid request data, missing resources, authentication failures, authorization problems, database issues, or unexpected application exceptions.

If each controller returns errors in a different format, clients must implement separate handling logic for different endpoints. Standardized API error responses solve this problem by defining a consistent structure for communicating failures.

In Spring Boot, developers can standardize error responses using custom error DTOs, ResponseEntity, @ExceptionHandler, @RestControllerAdvice, and Spring's problem-details support.

Example of an Inconsistent Error Response

{
  "error": "User not found"
}

Another endpoint might return a completely different structure:

{
  "statusCode": 400,
  "message": "Invalid input",
  "details": "Email is required"
}

These responses communicate similar information but use different field names and structures. A standardized response makes error handling easier for frontend applications, mobile applications, third-party integrations, and API consumers.

Example of a Standardized Error Response

{
  "timestamp": "2026-10-24T10:30:00Z",
  "status": 404,
  "error": "Not Found",
  "code": "USER_NOT_FOUND",
  "message": "The requested user could not be found",
  "path": "/api/users/100",
  "traceId": "abc123xyz"
}

This structure provides the HTTP status, a machine-readable error code, a readable message, the request path, and a correlation identifier that can help locate the corresponding server-side logs. The timestamp and trace identifier are optional design choices.

2. Learning Objectives

• Understand the purpose of standardized API error responses.
• Learn common HTTP status codes used in REST APIs.
• Create a reusable error-response DTO in Java.
• Handle exceptions using @ExceptionHandler.
• Implement centralized exception handling with @RestControllerAdvice.
• Handle request-validation errors consistently.
• Return meaningful errors for missing resources and invalid operations.
• Understand how Spring Boot problem-details support works.
• Apply security, logging, testing, and API-design best practices.

3. Why Standardized Error Responses Are Important

4. Understanding HTTP Status Codes

An API error response should use an HTTP status code that accurately describes the outcome. The response body provides additional details, while the status code communicates the broad category of the result.

Choose status codes according to the API contract and the actual failure. For example, do not return HTTP 200 for a failed operation merely because the response body contains an error message.

5. Designing a Standard Error Response Structure

A standardized error-response DTO should contain enough information for the client to understand and handle the error without revealing sensitive internal information.

Recommended Fields

Not every error needs every field. For example, a validation response may include a collection of field errors, while an unexpected server error should generally expose only a safe generic message.

6. Creating a Custom API Error DTO

A Data Transfer Object (DTO) defines the structure of the error response. Using a dedicated class prevents controllers from creating inconsistent maps and allows the response contract to evolve in a controlled way.

ApiError.java

package com.example.demo.exception;

import java.time.Instant;

public class ApiError {

    private Instant timestamp;
    private int status;
    private String error;
    private String code;
    private String message;
    private String path;
    private String traceId;

    public ApiError() {
    }

    public ApiError(
            Instant timestamp,
            int status,
            String error,
            String code,
            String message,
            String path,
            String traceId) {
        this.timestamp = timestamp;
        this.status = status;
        this.error = error;
        this.code = code;
        this.message = message;
        this.path = path;
        this.traceId = traceId;
    }

    public Instant getTimestamp() {
        return timestamp;
    }

    public void setTimestamp(Instant timestamp) {
        this.timestamp = timestamp;
    }

    public int getStatus() {
        return status;
    }

    public void setStatus(int status) {
        this.status = status;
    }

    public String getError() {
        return error;
    }

    public void setError(String error) {
        this.error = error;
    }

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public String getPath() {
        return path;
    }

    public void setPath(String path) {
        this.path = path;
    }

    public String getTraceId() {
        return traceId;
    }

    public void setTraceId(String traceId) {
        this.traceId = traceId;
    }
}

The Instant type represents a point on the UTC timeline. The status field should match the actual HTTP status returned by the server.

7. Creating Custom Application Exceptions

Custom exceptions represent meaningful failures in the application domain. Instead of throwing a generic exception for every problem, create specific exception classes for common conditions, such as a resource not being found.

ResourceNotFoundException.java

package com.example.demo.exception;

public class ResourceNotFoundException extends RuntimeException {

    public ResourceNotFoundException(String message) {
        super(message);
    }
}

ResourceConflictException.java

package com.example.demo.exception;

public class ResourceConflictException extends RuntimeException {

    public ResourceConflictException(String message) {
        super(message);
    }
}

These exceptions communicate the kind of failure that occurred. A centralized handler can translate each exception into an appropriate status code and standardized response body.

8. Implementing Global Exception Handling

Spring provides @RestControllerAdvice to centralize exception handling across REST controllers. Methods annotated with @ExceptionHandler can map specific exception types to appropriate HTTP responses.

GlobalExceptionHandler.java

package com.example.demo.exception;

import jakarta.servlet.http.HttpServletRequest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import java.time.Instant;

@RestControllerAdvice
public class GlobalExceptionHandler {

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

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(
            ResourceNotFoundException exception,
            HttpServletRequest request) {

        ApiError error = new ApiError(
                Instant.now(),
                HttpStatus.NOT_FOUND.value(),
                HttpStatus.NOT_FOUND.getReasonPhrase(),
                "RESOURCE_NOT_FOUND",
                exception.getMessage(),
                request.getRequestURI(),
                null
        );

        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }

    @ExceptionHandler(ResourceConflictException.class)
    public ResponseEntity<ApiError> handleConflict(
            ResourceConflictException exception,
            HttpServletRequest request) {

        ApiError error = new ApiError(
                Instant.now(),
                HttpStatus.CONFLICT.value(),
                HttpStatus.CONFLICT.getReasonPhrase(),
                "RESOURCE_CONFLICT",
                exception.getMessage(),
                request.getRequestURI(),
                null
        );

        return ResponseEntity.status(HttpStatus.CONFLICT).body(error);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiError> handleUnexpectedException(
            Exception exception,
            HttpServletRequest request) {

        log.error(
                "Unexpected error while processing request {}",
                request.getRequestURI(),
                exception
        );

        ApiError error = new ApiError(
                Instant.now(),
                HttpStatus.INTERNAL_SERVER_ERROR.value(),
                HttpStatus.INTERNAL_SERVER_ERROR.getReasonPhrase(),
                "INTERNAL_SERVER_ERROR",
                "An unexpected error occurred. Please try again later.",
                request.getRequestURI(),
                null
        );

        return ResponseEntity
                .status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(error);
    }
}

How the Global Handler Works

1. A controller or service throws an exception.
2. Spring searches for an applicable exception handler.
3. The matching method converts the exception into an API error DTO.
4. The handler returns a suitable HTTP status and response body.
5. The client receives a consistent error structure.

The generic handler logs the unexpected exception on the server but returns a safe message to the client. In production, avoid returning stack traces, SQL statements, database credentials, or internal class names in API error responses.

Important: A broad @ExceptionHandler(Exception.class) should not replace specific handlers for expected errors. Spring MVC, request conversion, validation, and security can produce other exception types that may require separate mappings or framework-specific handling.

9. Using the Standard Error Response in a Service

The service layer should throw meaningful exceptions when an operation cannot be completed. The global handler then converts those exceptions into HTTP responses.

UserService.java

package com.example.demo.service;

import com.example.demo.exception.ResourceNotFoundException;
import org.springframework.stereotype.Service;

@Service
public class UserService {

    public String findUserById(Long id) {
        // Demonstration only. Replace this condition with
        // a real repository lookup in an actual application.
        if (id == null || id != 1L) {
            throw new ResourceNotFoundException(
                    "The requested user could not be found"
            );
        }

        return "User found";
    }
}

UserController.java

package com.example.demo.controller;

import com.example.demo.service.UserService;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/{id}")
    public String getUser(@PathVariable Long id) {
        return userService.findUserById(id);
    }
}

When a request is made to /api/users/100, the demonstration service throws ResourceNotFoundException. The global handler maps it to HTTP 404 with the standard error-response format.

10. Standardizing Validation Error Responses

Request validation is a frequent source of API errors. In Spring MVC, validation of an object annotated with @Valid commonly results in MethodArgumentNotValidException when constraints fail.

For validation responses, it is useful to include a list of field errors instead of only a single message.

FieldErrorDetail.java

package com.example.demo.exception;

public class FieldErrorDetail {

    private String field;
    private String message;

    public FieldErrorDetail(String field, String message) {
        this.field = field;
        this.message = message;
    }

    public String getField() {
        return field;
    }

    public String getMessage() {
        return message;
    }
}

ValidationErrorResponse.java

package com.example.demo.exception;

import java.time.Instant;
import java.util.List;

public class ValidationErrorResponse {

    private Instant timestamp;
    private int status;
    private String error;
    private String code;
    private String message;
    private String path;
    private List<FieldErrorDetail> fieldErrors;

    public ValidationErrorResponse(
            Instant timestamp,
            int status,
            String error,
            String code,
            String message,
            String path,
            List<FieldErrorDetail> fieldErrors) {
        this.timestamp = timestamp;
        this.status = status;
        this.error = error;
        this.code = code;
        this.message = message;
        this.path = path;
        this.fieldErrors = fieldErrors;
    }

    public Instant getTimestamp() {
        return timestamp;
    }

    public int getStatus() {
        return status;
    }

    public String getError() {
        return error;
    }

    public String getCode() {
        return code;
    }

    public String getMessage() {
        return message;
    }

    public String getPath() {
        return path;
    }

    public List<FieldErrorDetail> getFieldErrors() {
        return fieldErrors;
    }
}

Validation Exception Handler

import com.example.demo.exception.FieldErrorDetail;
import com.example.demo.exception.ValidationErrorResponse;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import java.time.Instant;
import java.util.List;

@RestControllerAdvice
public class ValidationExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ValidationErrorResponse> handleValidation(
            MethodArgumentNotValidException exception,
            HttpServletRequest request) {

        List<FieldErrorDetail> errors =
                exception.getBindingResult()
                        .getFieldErrors()
                        .stream()
                        .map(error -> new FieldErrorDetail(
                                error.getField(),
                                error.getDefaultMessage() == null
                                        ? "Invalid value"
                                        : error.getDefaultMessage()
                        ))
                        .toList();

        ValidationErrorResponse response =
                new ValidationErrorResponse(
                        Instant.now(),
                        HttpStatus.BAD_REQUEST.value(),
                        HttpStatus.BAD_REQUEST.getReasonPhrase(),
                        "VALIDATION_FAILED",
                        "One or more fields contain invalid values",
                        request.getRequestURI(),
                        errors
                );

        return ResponseEntity.badRequest().body(response);
    }
}

Note: The Stream.toList() method is available in Java 16 and later. If you use an earlier Java version, use collect(Collectors.toList()). The example uses a separate advice class for clarity; in a real project, these handlers can be combined into one global advice to avoid overlapping handler definitions.

Example Validation Response

{
  "timestamp": "2026-10-24T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "code": "VALIDATION_FAILED",
  "message": "One or more fields contain invalid values",
  "path": "/api/users",
  "fieldErrors": [
    {
      "field": "name",
      "message": "Name is required"
    },
    {
      "field": "email",
      "message": "Enter a valid email address"
    }
  ]
}

Using a list allows multiple constraint violations for the same field to be represented. It also makes it easier for web and mobile clients to highlight the appropriate input controls.

11. Using Spring Problem Details

Spring Framework 6 and Spring Boot 3 support the Problem Details standard defined by RFC 9457. It provides a common format for communicating HTTP API errors. Spring MVC applications can use ProblemDetail and related support instead of creating an entirely custom format.

A typical problem-details response can include fields such as type, title, status, detail, and instance. Applications may also add extension properties for machine-readable codes or validation details.

Example Using ProblemDetail

import jakarta.servlet.http.HttpServletRequest;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import java.net.URI;

@RestControllerAdvice
public class ProblemDetailsExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ProblemDetail> handleNotFound(
            ResourceNotFoundException exception,
            HttpServletRequest request) {

        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
                HttpStatus.NOT_FOUND,
                exception.getMessage()
        );

        problem.setTitle("Resource Not Found");
        problem.setType(URI.create(
                "https://www.justacademy.co/problems/resource-not-found"
        ));
        problem.setInstance(URI.create(request.getRequestURI()));
        problem.setProperty("code", "RESOURCE_NOT_FOUND");

        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(problem);
    }
}

The type URI should identify documentation for the problem type. In a real application, publish a stable documentation URL under a domain you control rather than using a course website as a placeholder. The example demonstrates the API structure; the URI should be replaced before production use.

Do not mix a custom error DTO and a Problem Details response format randomly across endpoints. Choose one documented API contract or clearly define where each format applies.

12. Handling Authentication and Authorization Errors

Spring Security can reject requests before they reach a controller. For example, unauthenticated requests may be handled by an AuthenticationEntryPoint, while authenticated users who lack permission may be handled by an AccessDeniedHandler.

A controller's @RestControllerAdvice alone may not handle all security failures because the Spring Security filter chain can process them before MVC controller handling begins. To standardize these responses, configure the security handlers to use the same error contract.

Conceptual Security Error Format

{
  "status": 401,
  "error": "Unauthorized",
  "code": "AUTHENTICATION_REQUIRED",
  "message": "Authentication is required to access this resource",
  "path": "/api/profile"
}

For a forbidden operation, use HTTP 403 when appropriate:

{
  "status": 403,
  "error": "Forbidden",
  "code": "ACCESS_DENIED",
  "message": "You do not have permission to perform this operation",
  "path": "/api/admin/reports"
}

Authentication and authorization responses should avoid disclosing whether a protected account, internal resource, or sensitive record exists when such disclosure would create a security risk. Ensure the HTTP status and body remain consistent with the configured security policy.

13. Logging and Trace IDs

Standardized errors are more useful when they can be correlated with server logs. A trace ID or request correlation ID helps developers connect a client-visible failure to its corresponding log entries.

• Generate or obtain a trusted correlation ID for each request.
• Include the ID in structured server logs.
• Return the ID in the error response when it is safe and useful.
• Validate incoming correlation IDs before accepting them from external clients.
• Avoid logging passwords, access tokens, payment details, or other sensitive request values.
• Log unexpected exceptions with enough context to investigate the failure.

For distributed systems, use established tracing infrastructure where possible. A trace ID should be generated or propagated according to a defined policy rather than copied blindly from an untrusted header.

14. Error Handling Best Practices

• Use a consistent response schema across all API endpoints.
• Return the correct HTTP status code for the failure.
• Use stable machine-readable error codes such as USER_NOT_FOUND or VALIDATION_FAILED.
• Keep client-facing messages concise, understandable, and safe.
• Use @RestControllerAdvice for centralized MVC exception handling.
• Use specific exception handlers for expected failures and a generic handler for unexpected errors.
• Keep database and business logic out of the controller's error-formatting code.
• Handle Spring Security exceptions through the appropriate security configuration.
• Document error schemas and status codes in the API documentation.
• Do not expose stack traces, SQL queries, internal server paths, or secrets.
• Do not treat every exception as HTTP 400; distinguish client errors from server failures.
• Avoid returning HTTP 200 for failed requests simply to simplify client handling.
• Make validation responses suitable for displaying field-level messages.
• Test error responses as carefully as successful API responses.
• Keep the response format backward-compatible when possible.

15. Common Mistakes and Troubleshooting

16. Testing Standardized API Error Responses

Tests should verify the status code, content type, error code, message, and important fields in the response. In Spring Boot, controller integration tests can use MockMvc to check the behavior of the complete MVC request-processing pipeline.

Example MockMvc Test

import com.example.demo.exception.ResourceNotFoundException;
import com.example.demo.service.UserService;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.context.annotation.Import;
import org.springframework.test.web.servlet.MockMvc;

import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@WebMvcTest(UserController.class)
@Import(GlobalExceptionHandler.class)
class UserControllerErrorTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserService userService;

    @Test
    void shouldReturnStandardNotFoundResponse() throws Exception {

        when(userService.findUserById(100L))
                .thenThrow(new ResourceNotFoundException(
                        "The requested user could not be found"
                ));

        mockMvc.perform(get("/api/users/100"))
                .andExpect(status().isNotFound())
                .andExpect(jsonPath("$.status").value(404))
                .andExpect(jsonPath("$.code")
                        .value("RESOURCE_NOT_FOUND"))
                .andExpect(jsonPath("$.message")
                        .value("The requested user could not be found"))
                .andExpect(jsonPath("$.path")
                        .value("/api/users/100"));
    }
}

Version note: Depending on your Spring Boot version, test annotations such as @MockBean may be deprecated in favor of newer bean-override test support. Use the test APIs supported by your project's version.

Testing Checklist

• Verify the HTTP status matches the error scenario.
• Verify the response uses the expected JSON content type.
• Verify the machine-readable error code is stable.
• Verify validation failures include the relevant field names.
• Verify unexpected exceptions do not expose internal details.
• Verify authentication and authorization failures use the documented schema.
• Verify successful requests are not affected by error-handling configuration.

17. Practical Project Exercise

Project: Build a standardized error-handling layer for a User Management REST API.

Requirements

• Create a user retrieval endpoint using GET /api/users/{id}.
• Return HTTP 404 when a user cannot be found.
• Return HTTP 409 when a user creation request conflicts with an existing record.
• Validate user registration data and return HTTP 400 for invalid fields.
• Create a common error-response DTO with status, code, message, timestamp, and path.
• Implement global exception handling using @RestControllerAdvice.
• Return a safe HTTP 500 response for unexpected errors.
• Add structured logging and a request correlation ID.
• Configure security error handling if the API uses Spring Security.
• Write MockMvc tests for each major failure scenario.

Expected Error Scenarios

18. Interview Questions and Answers

Q1. What is a standardized API error response?

Answer: It is a consistent format used by API endpoints to communicate failures. It typically includes an HTTP status, error code, message, and optional details such as a timestamp, path, or trace ID.

Q2. Why should API errors use standard HTTP status codes?

Answer: HTTP status codes communicate the general category of a result. Standard status codes make it easier for clients, gateways, monitoring tools, and developers to interpret failures consistently.

Q3. What is the purpose of @RestControllerAdvice?

Answer: It provides centralized exception handling for REST controllers, allowing the application to convert exceptions into consistent HTTP responses.

Q4. What is the difference between @ExceptionHandler and @RestControllerAdvice?

Answer: @ExceptionHandler identifies a method that handles a specific exception type. @RestControllerAdvice applies controller advice globally and supports response-body serialization for handled exceptions.

Q5. Why create a custom error DTO?

Answer: A custom DTO defines a predictable response contract and prevents each controller from inventing its own error structure.

Q6. When should an API return HTTP 404?

Answer: HTTP 404 is appropriate when the requested resource cannot be found or is not available at the requested location, subject to the application's security and resource-disclosure policy.

Q7. What is the difference between HTTP 401 and HTTP 403?

Answer: HTTP 401 generally indicates that valid authentication is missing or has failed. HTTP 403 indicates that the request is not permitted, often because the authenticated caller lacks sufficient authorization.

Q8. How should validation errors be represented?

Answer: A validation response can include a general error code and a list of field-level errors, allowing clients to identify and correct individual invalid values.

Q9. Why should stack traces not be returned to clients?

Answer: Stack traces can expose internal implementation details, file paths, library information, and other sensitive data. Technical details should be logged securely on the server.

Q10. What is Spring Problem Details support?

Answer: It is Spring's support for the standardized problem-details format defined by RFC 9457. It provides a consistent representation for HTTP API errors.

Q11. Why might @RestControllerAdvice not handle a security error?

Answer: Spring Security can reject requests in its filter chain before controller execution. Authentication and access-denied failures may need dedicated security handlers.

Q12. What is a correlation ID?

Answer: It is an identifier used to connect a request and its related log entries across application components or services. It can help investigate failures without exposing sensitive implementation details to the client.

19. Quick Revision Checklist

• Standardized error responses provide a consistent API contract.
• Choose accurate HTTP status codes for each failure.
• Use a reusable DTO or a documented Problem Details format.
• Use specific custom exceptions for expected application failures.
• Centralize controller exception handling with @RestControllerAdvice.
• Use @ExceptionHandler to map exceptions to response bodies and status codes.
• Return field-level details for validation errors when useful.
• Configure Spring Security error handlers separately where necessary.
• Log unexpected exceptions without exposing internal details to clients.
• Use stable error codes and correlation IDs where appropriate.
• Test error responses and document them in the API contract.
• Keep the response schema consistent across endpoints and versions.

20. Conclusion

Creating standardized API error responses is an essential practice in Spring Boot application development. It improves consistency, simplifies client-side error handling, supports troubleshooting, and helps protect internal implementation details.

By creating a reusable error DTO, defining meaningful application exceptions, using centralized exception handling, and testing all major failure scenarios, developers can build REST APIs that are easier to maintain and integrate with other systems.

To develop your Java and Spring Boot skills further, explore the Advanced Java Training course at JustAcademy. You can also register for a course demo or visit the JustAcademy website.