Specify how error details are returned

[msporny]

The group discussed this on 2023-01-10. @dlongley noted that he was ambivalent about whether or not everything has an error response. If there are values that need to be sent back to be acted upon vs. all information being communicated via status -- that seems to be the most important thing. Ideally, we don't invent our own thing for error codes or the error data model -- there is some RFC that Mark Nottingham might have put together for HTTP Errors, don't know if anyone uses it, don't know if it fits our use cases, might not match up with how errors are returned from some implementations today -- some implementations use name field to match JavaScript errors, might be problematic for a W3C spec -- a number of considerations. @jandrieu asked "what is the framework for extensibility in the responses?" -- there might be open ended things to pass back. @msporny noted that current error response has id which is mandatory, description which contains explanatory text, and details which can contain arbitrary infomation from the implementation. @dlongley noted that id is problematic and maybe we should use name instead. @jandrieu agreed.

Do we want to always return an error object on an error? @TallTed noted mandating minimal requirements but allowing for larger responses -- as a troubleshooter, want detailed errors, could be configurable/switchable. That is implementation specific. Leave the door open for implementations to provide sufficient information to troubleshoot information that's erroring. @dlongley noted that we shouldn't ALWAYS return an error code until we it's clear that we should. We need to find cases where HTTP status code is insufficient and mandate detailed errors through that mechanism, but only when necessary. An implementation is allowed to return an ErrorResponse if it chooses to do so, and those errors might not be the same across implementations UNLESS it is specified to be the same by the specification. @PatStLouis noted that covering all status codes is a must, two different errors could return the same error code, would be good to know the reason for it ... for cases where implementer wants to return more detail, good to have a pre-defined schema, but leave content to implementer.

The group arrived at consensus on the following:

1. Errors will, at a minimum, be conveyed using HTTP error response codes.
2. Implementers MAY return error responses using the ErrorResponse schema, or their own, (for any HTTP error).
3. The specification MAY (at a later date) define specific ErrorResponses in specific situations.

@dlongley NOTE: We might want to just say error response is JSON and not use a suggested schema and that can be bike shedded in the PR.

@PatStLouis asked if we wanted to have a negative test and analyze response to match the test, might be easier to do if there is a pre-defined error schema. @dlongley noted that if we are going to do that, we might mandate that you have to have something in the spec -- so, either test suite is going to look for HTTP status codes, or we find cases where we know where we want the errors to be and mandate those. We shouldn't do something in between that and it becomes "de-facto".

Originally posted by @msporny in https://github.com/w3c-ccg/vc-api/issues/326#issuecomment-1377842920

[msporny]

Cross-referencing with https://github.com/w3c/vc-data-integrity/issues/136 which is dealing with a similar problem, and a number of implementations utilize the VC API. That specification might use RFC 7807, which would make sense for this specification as well.

[msporny]

Take a look at this for an idea on how errors might be exposed to a caller: https://pr-preview.s3.amazonaws.com/w3c/vc-data-model/pull/1338.html#problem-details

[msporny]

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