API - Make ambiguous 409 error causes distinguishable

[ezdac]

Abstract

The semantic of the 409 error code is different for different REST endpoints. This is fine as long as the error only represents one specific internal cause of error.

But e.g for the POST /payment endpoint, the 409 error can have 3 causes:

• If the address or the amount is invalid - related to input encoding of address + amount fields
• if there is no path to the target - related to funding / online status of nodes
• if the identifier is already in use for a different payment - related to manual input of id field

Since an API-consumer would have to react to every of the error causes differently - and since software could react to the errors programatically, the error causes should be distinguishable and machine readable.

Motivation

As a consumer of the API, I want to be able to react to ambiguous error causes differently, and I don't want to parse a flat string that is not intended for machine-readability.

Specification

Where applicable, ambiguous error codes should either:

• be split to different error code, where the semantics are provided by differing "endpoints"
• return a machine parsable body (e.g. JSON), that has a pre-defined schema with known error entities

Backwards Compatibility

Most likely not backwards compatible:

• if the schema of the error message will be changed, there might be a small possibility that API consumers were parsing the flat string
• if the error codes will be split up, the interface will be broken anyways