RFC 7807 Problem Details

HTTP Status Code is not enough to describe problem in HTTP interaction. And people offen feel confused with HTTP layer status code and business layer status code.

For example, if you have a 404 response, you may think, is it really "404 Resource Not Found"? Is it possible to call a wrong API address or backend server register it's HTTP handler on wrong URL address?

RFC 7807 defines a standard JSON/XML format to describe what error is in business layer.

Format

JSON

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

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

XML

HTTP/1.1 403 Forbidden
   Content-Type: application/problem+xml
   Content-Language: en

   <?xml version="1.0" encoding="UTF-8"?>
   <problem xmlns="urn:ietf:rfc:7807">
     <type>https://example.com/probs/out-of-credit</type>
     <title>You do not have enough credit.</title>
     <detail>Your current balance is 30, but that costs 50.</detail>
     <instance>https://example.net/account/12345/msgs/abc</instance>
     <balance>30</balance>
     <accounts>
       <i>https://example.net/account/12345</i>
       <i>https://example.net/account/67890</i>
     </accounts>
   </problem>

Key Fields

application/problem+json and application/problem+xml

New media types are registered - application/problem+json and application/problem+xml.

Mandatory Fields

type (string): a HTTP URL as identify of a problem type
title (string): A short, human-readable summary of the problem type
status (number): Same as HTTP status code
detail (string): A human-readable explanation specific to this occurrence of the problem
instance (string): A URI reference that identifies the specific occurrence of the problem

Extension Fields

There is no definition of extension fields in RFC. We can define whatever we need in problem details object.

However, for a public API service, we're better not to assume the HTTP client understand the customized extension fields.

References

RFC 7807: Problem Details for HTTP APIs