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.
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"]
}
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>
New media types are registered - application/problem+json and application/problem+xml.
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.