Problem Details for standard error format in Spring Boot

Introduction

Problem Details provide a simple, consistent way to show errors in web APIs. It helps clients understand what went wrong without confusion.

When your API needs to tell clients about errors clearly.

When you want to follow a common standard for error messages.

When you want to include details like error type, message, and status code.

When you want to make debugging easier for API users.

When you want to support automatic error handling in clients.

Syntax

Spring Boot

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "status": 400,
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/transactions/abc"
}

The Content-Type must be application/problem+json to follow the standard.

Fields like type, title, status, detail, and instance help describe the error clearly.

Examples

A typical JSON response showing a problem with credit balance.

Spring Boot

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "status": 400,
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/transactions/abc"
}

Example for a 'not found' error using the standard format.

Spring Boot

{
  "type": "https://example.com/probs/not-found",
  "title": "Resource not found.",
  "status": 404,
  "detail": "The requested item was not found in the database.",
  "instance": "/items/999"
}

Sample Program

This Spring Boot controller returns a problem detail error when the item is not found. It uses the standard format to describe the error.

Spring Boot

package com.example.demo;

import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import java.net.URI;

@RestController
public class ItemController {

    @GetMapping("/items/{id}")
    public ResponseEntity<?> getItem(@PathVariable int id) {
        if (id != 1) {
            ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);
            problem.setType(URI.create("https://example.com/probs/not-found"));
            problem.setTitle("Resource not found.");
            problem.setDetail("Item with id " + id + " was not found.");
            problem.setInstance(URI.create("/items/" + id));
            return ResponseEntity.status(HttpStatus.NOT_FOUND).body(problem);
        }
        return ResponseEntity.ok("Item 1 details");
    }
}

Important Notes

Spring Boot 3+ supports ProblemDetail class to create standard error responses easily.

Always set the Content-Type header to application/problem+json for clients to recognize the format.

Use meaningful type URIs to help clients find more info about the error.

Summary

Problem Details standardize error messages in APIs for clarity.

Use fields like type, title, status, detail, and instance.

Spring Boot provides built-in support to create these error responses easily.