Год назад вышло RFC с предложением стандартизировать описание ошибок в HTTP, чтобы дополнить status codes.
Интересна мотивация:
HTTP status codes cannot always convey enough information about errors to be helpful. While humans using web browsers can often understand an HTML response content, non-human consumers of HTTP APIs have difficulty doing so.
Т.е. никто уже не стесняется говорить, что честное HTTP API нормально ложится на сайтики, но как еж на кактус натягивается на межсервисные взаимодействия.
Ничего сверхнового авторы не предлагают, такое лет 10-15 в энтерпрайзных апи гайдах делают. Но выглядит приятно, пусть хотя бы такая стандартизация будет.
Вот так это должно выглядеть:
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 422 Unprocessable Content
Content-Type: application/problem+json
Content-Language: en
{
"type": "https://example.net/validation-error",
"title": "Your request is not valid.",
"errors": [
{
"detail": "must be a positive integer",
"pointer": "#/age"
},
{
"detail": "must be 'green', 'red' or 'blue'",
"pointer": "#/profile/color"
}
]
}