1. Definition

For in-depth knowledge, visit: Problem Details for HTTP APIs by the Internet Engineering Task Force (IETF).

This definition is borrowed from the article linked before:

ProblemDetails is a way to carry, machine-readable details of errors in an HTTP response, to avoid the need to define new error formats for HTTP APIs.

This one is translated to something that I can understand and remember:

ProblemDetails instance is an industry-standard error response which can help non-human consumers of HTTP APIs to understand the cause of the error in a better way and/or steps that can be taken to resolve it.

2. Media-type

• JSON: "application/problem+json"

• XML: "application/problem+xml"

3. Why return a ProblemDetails Instance?

ProblemDetails instance represents errors in an HTTP API. This can help non-human consumers of the HTTP API to understand the error and then take steps to correct it.

HTTP status codes are sometimes not sufficient to convey enough information about an error to be helpful. While humans can be informed about the nature of the problem with an HTML response body (parsed with the help of web browsers), non-human consumers of so-called "HTTP APIs" are usually not.

ProblemDetails instance helps in informing the non-human consumers of "HTTP APIs" about the nature of the problem returned. So, API clients can be informed of:

• The high-level error class (using the status code)

• The finer-grained details of the problem (using the ProblemDetails)

after which they can read and treat this ProblemDetails response appropriately.

4. Members of a ProblemDetails Instance

Consider the following JSON object, that we will use to describe the members of the ProblemDetails instance:

{
    "type": "https://example.com/not-found",
    "title": "Not Found",
    "status": 404,
    "detail": "The resource you requested does not exist.",
    "instance": "api/orders/3"
}

• type: String: A URI reference that identifies the problem type.

  This property is optional, but it is recommended that you use it to provide a standard way to identify errors. When the value of this property is NOT about:blank, it should point to a document that provides human-readable documentation for the problem type.

• title: String: A short, human-readable summary of the problem type.

  It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. For example, "title": "Not Found" is a short, human-readable summary of the problem type, but it does not go into detail (for its explanation we have detail).

  • Use the same title for the same problem type, even if the error occurs in different places.

  • Keep it short.

• status: Int32: The HTTP status code generated by the origin server for this occurrence of the problem. For details visit - Status Codes.

• detail: String: A human-readable explanation specific to this occurrence of the problem.

  It MAY be used to provide additional information about the error, such as the cause of the error or steps that can be taken to resolve the error. For example, "detail": "The resource you requested does not exist.", provides more information about the error, such as the possible cause of the error.

  • Use human-readable/plain language that is easy to understand.

  • Be specific.

  • Avoid technical jargon.

  • Provide as much information as possible about the error.

• instance: String: A URI reference that identifies the specific occurrence of the problem.

  It MAY be used to provide additional information about the error, such as the ID of the resource that was not found or the timestamp of the error. For example, "instance": "api/orders/7, this is the URI of the order that was not found. The instance property is a useful way to provide information about an error. This can be helpful for users who are trying to understand why an error occurred. It can also be helpful for developers who are trying to debug and fix errors.

  • Use a unique URI for each occurrence of the problem.

  • Use a URI that is meaningful to the user or developer.

  • Avoid using URIs that are too long or complex.