Problem details for HTTP APIs

Communicate API errors using a well-defined standard.

The Problem Details standard (RFC 9457) describes a format for describing a wide range of API errors.

It can be used to extend the HTTP protocol specification according to business needs.

An example of a problem detail response might look like:

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

{
  "type": "https://api.bankingexample.com/errors/unverified-customer",
  "title": "The customer has not been verified.",
  "status": 400,
  "detail": "'verification_status' must be 'verified' to open an account but it is 'verification_pending'.",
  "instance": "/customers/cust_123"
}

Problem types

The Problem Details standard expects that error types are formatted as URIs. This is an important difference from many popular APIs, which use numeric codes or enum strings.

The type URIs do not have to point to anything, but it is a good idea to have them point to a page in your API's documentation to explain the error in further detail. If you describe all possible error reasons on the same page in your documentation, you can still define a unique type identifier by using URI fragments:

https://example.com/docs/errors#unverified-customer

Pros

Industry standard: The problem details standard avoids the need to reinvent the wheel. Developers also benefit from consistency across different API vendors.
Extensible: The standard foresees and accomodates the need for API providers to extend specific problems with domain-specific information.

Cons

Separate content type: The content type of problem detail responses is defined as application/problem+json or application/problem+xml. This may pose a problem for clients that expect the content type for errors to be the same as for successful responses.
Problem types are URIs: Many APIs use numeric or string codes to identify different types of errors. Adopting URIs may require some upfront planning.
Validation errors not standardized: The problem details standard does not recommend any particular format for communicating request validation errors.

OpenAPI implementation

{
  "openapi": "3.1.0",
  "info": {
    "title": "Problem Details Example API",
    "version": "1.0.0"
  },
  "paths": {
    "/records": {
      "get": {
        "summary": "list all records",
        "responses": {
          "default": {
            "description": "Error",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetail"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProblemDetail": {
        "title": "An RFC 9457 problem object",
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri-reference",
            "description": "A URI reference that identifies the problem type."
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code generated by the origin server for this occurrence of the problem.",
            "minimum": 100,
            "maximum": 599
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence of the problem."
          },
          "instance": {
            "type": "string",
            "format": "uri-reference",
            "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced."
          }
        }
      }
    }
  }
}