RFC 9457 standardizes the structure for conveying machine-readable details of errors in HTTP responses. This facilitates a consistent approach for API clients to diagnose and rectify issues based on the error details provided by the server.

Details

The “Problem Details” pattern is a JSON-based structure that provides a standardized format for error responses in HTTP APIs. Key fields include:

  • type: A URI identifying the problem type, typically pointing to documentation.
  • title: A concise summary of the problem.
  • status: The HTTP status code associated with the problem.
  • detail: A detailed explanation of the issue specific to the occurrence.
  • instance: A URI that points to the specific instance of the problem.

This format can be extended with additional fields to provide more detailed diagnostics, enabling APIs to deliver precise error information that is both human-readable and machine-interpretable.

Common Use Cases

  • Client Error Handling: Assists clients in understanding specific errors in their requests to facilitate corrections.
  • Logging and Diagnostics: Improves error tracking and diagnostics with uniform error message structures.
  • User Feedback: Enhances error information presentation in user interfaces or logs, making them more intelligible.

Mermaid Sequence Diagram

This diagram illustrates the typical use of the Problem Details pattern in handling HTTP error responses:

sequenceDiagram
    participant Client
    participant Server
    Client->>Server: HTTP Request
    alt success
        Server->>Client: HTTP 200 (OK)
    else validation error
        Server->>Client: HTTP 400 (Bad Request)
        Server->>Client: Problem Details JSON
    else internal error
        Server->>Client: HTTP 500 (Internal Server Error)
        Server->>Client: Problem Details JSON
    end

Examples with Requests and Responses

Example 1: Validation Error

HTTP Request

POST /create-user HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "John Doe",
  "age": 125
}

HTTP Response

{
  "type": "https://example.com/probs/out-of-range",
  "title": "Value out of range",
  "status": 400,
  "detail": "The field 'age' must be between 0 and 120.",
  "instance": "/request/12345"
}

Scenario: A client sends a POST request to create a user, but the age field violates the server’s validation rules. The server responds with a Problem Details object specifying the exact issue and guidance.

Example 2: Internal Server Error

HTTP Request

GET /resource/data HTTP/1.1
Host: example.com
Accept: application/json

HTTP Response

{
  "type": "https://example.com/probs/internal-server-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected condition was encountered.",
  "instance": "/request/67890"
}

Scenario: A GET request that typically functions correctly fails due to an unexpected server error, prompting a detailed Problem Details response for better diagnosis and future troubleshooting.

This comprehensive approach to documenting and handling HTTP API errors aligns with modern best practices, ensuring that both API consumers and maintainers have the necessary tools to efficiently address issues as they arise.

Updated: