Error handling API, should we use headers to let the Frontend know?

[Brend-Smits]

In GitLab by @Brend-Smits on Apr 19, 2020, 13:21

How should we let the frontend know what went wrong? Normally I create new headers and add those to the request if something went wrong for whatever reason. The frontend can intercept the requests and check if the headers are populated and act accordingly.

[wotwot563]

I suggest we follow rfc7807 which aims to unify the error message format.
https://tools.ietf.org/html/rfc7807

A short example of the format:
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"]
}

In detail:
A problem details object can have the following members:

o "type" (string) - A URI reference [RFC3986] that identifies the
problem type. This specification encourages that, when
dereferenced, it provide human-readable documentation for the
problem type (e.g., using HTML [W3C.REC-html5-20141028]). When
this member is not present, its value is assumed to be
"about:blank".

o "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 (e.g., using
proactive content negotiation; see [RFC7231], Section 3.4).

o "status" (number) - The HTTP status code ([RFC7231], Section 6)
generated by the origin server for this occurrence of the problem.

o "detail" (string) - A human-readable explanation specific to this
occurrence of the problem.

o "instance" (string) - A URI reference that identifies the specific
occurrence of the problem. It may or may not yield further
information if dereferenced.

for easy error checking the rfc allows some flexibility.
so i further propose that we embed the json object with the key "error" so it is easier to see the difference between an error and valid data.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en
{
"error":
{
"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"]
}
}