Problem Details

Problem Details is a standardized way to express error situations in a JSON Web API.

Problem Details is defined in RFC7807

Summary

Sometimes a simple HTTP Status Code isn't enough to convey the details of a response. While an HTML page might suffice for a human, programmatic consumers of your API need something more standardized.

The Problem Details RFC suggests a structure to make it possible to distinguish different errors from one another.

Members of Problem Details

type: string

A URI that uniquely identifies the problem. This is used by the consumer of the API to determine which error has occurred. Different occurrences of the same type of error should use the same type value.

title: string

A human-readable name for the problem. This should not change between different occurrences of the same type of problem. The exception is to localize the title.

status: number

The HTTP status code of the response. This is included to preserve the status code in case it is changed by a proxy or cache before reaching the API consumer. It also preserves the status if the response is stored for later review, such as in a log message.

detail: string

A human-readable explanation of the specific occurrence of problem. API consumers should not try to parse this for information, instead extra members should be defined (see below).

instance: string

A URI that identifies the specific occurrence of the problem. This could dereference to a more detailed explanation of the specific occurrence.

Extra Members

When defining a new type of problem details it's encouraged to include any additional data in dedicated fields alongside the ones defined above.

When Not To Use Problem Details

When an HTTP Status Code is able to convey enough meaning by itself, no new problem details is necessary. If you want to keep consistency with other types of errors, the recommended solution is to omit the type field or set it to about:blank to indicate not specific information is available for the error. The title field should be set to the status phrase of the status, e.g. "Not Found" for status code 404.

Remember Security

As always when exposing something on the internet, be wary of what information you're serving up. While Problem Details enables and encourages providing more details, care should be taken when exposing extra information regarding an error. Carefully verify that all information included can't be exploited or compromised.