proposition to follow rfc9457 for API errors

[lemoustachiste]

RFC 9457 (https://www.rfc-editor.org/rfc/rfc9457.html) defines a Problem Details response for HTTP APIs.

It proposes a standard response object to explicit the error (instead of just returning error status for instance). By having an expectable shape for errors, it makes error handling easier and more consistent across various providers in the client (for instance to display feedback to the user).

To quote from the above linked document:

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.

[msporny]

The discussed this on the 2024-05-14 call:

@msporny Noted that we use RFC 9457 in vc-data-model. @dlongley noted that we wanted it to be easy to implement API w/o being too prescriptive on errors. There was some concern around using type and name, not URL. Maybe we want to mix those two together. We didn't have good implementation experience with it last time, didn't want to be too prescriptive. Generally, a good idea, will need to link to other issue that talks about this.

This issue is ready for a PR to say that implementations SHOULD use RFC 9457 to express problems over HTTP. We can re-use most of the text here: https://w3c.github.io/vc-data-model/#problem-details

[PatStLouis]

I suggest to close #340 and #331 since they can be addressed by the same PR

[msporny]

PR #389 has been merged, which addresses this issue. Closing.