HTTP API spec: update error response structure

[jiyoontbd]

Our current error object in the http api spec follows error object structure in json:api spec.

However, the set of fields inside each error object either a) doesn't apply well to the kind of details a PFI might want to return, or b) is not relevant at all.

Below is an example of the proposed new error response structure:

{
  "message": "Missing field: payin.amount",
  "id": "9af2bf88-e4f4-4f81-8ba9-55eaeeb718e2",
  "code": "TBDEX_MESSAGE_VALIDATION_ERROR",
  "details": [{ 
    "message": "Payin amount must be present.",
    "path": "$.payin.amount" 
  }]
}

Error response structure

Field	Type	Required	Description
message	String	Y	A human-readable explanation specific to this occurrence of the problem.
id	String	N	Optional server-generated request-specific ID, useful for diagnosing unexpected errors
code	String	Y	An application-specific error code, expressed as a string value.
details	ErrorDetail[]	N	Optional array of ErrorDetail objects

ErrorDetail structure

Field	Type	Required	Description
message	String	N	A human-readable explanation specific to this occurrence of the problem.
path	String	N	Path where validation failed (i.e. JSON schema path)

The introduction of a required code field is significant - this implies that the spec would need to provide specific code strings and when a PFI would want to use it to form the error response body.

The reason for code being a required field is that it would significantly reduce the amount of "error deduction" that wallet developers would have to do when parsing the error, as the top level message field (arbitrary string set by the PFI) + HTTP status code may not provide enough context. With the introduction of code field, the wallet developer can focus on displaying the appropriate error message depending on the known codes.

[kirahsapong]

Just floating an idea - what do you think about also adding an optional URL field where a consumer can navigate to learn more about the error code? It also offers a layer so we can add more documentation or troubleshooting steps to the given error case without needing to update the implementation.

Example:

{
  "message": "Missing field: payin.amount",
  "id": "9af2bf88-e4f4-4f81-8ba9-55eaeeb718e2",
  "code": "TBDEX_MESSAGE_VALIDATION_ERROR",
  "details": [{ 
    "message": "Payin amount must be present.",
    "path": "$.payin.amount" 
  }],
 "url": "https://github.com/TBD54566975/tbdex/some/url/to/errors/documentation"
}

Totally cool if it's not the move