API Error Standards

Errors should provide enough information for the consumer of the API to understand what they did wrong (or that they didn't do anything wrong) but at the same time the error message shouldn't provide enough information for a bad actor to interrogate the backend and expose potential exploits.

Transaction Header

There should be a common transaction header that is set on each transaction. If the request does not have a header, the API should add it and, where possible, pass it along to dependent systems to be included in logging.

X-myco-tx: 127c4e701b9529cb92a9950a96c383ae

This unique tag can then be used when research root cause on the backend.

Standard Error Format

The response from the API can contain multiple errors (in order to keep the developer from having to come back multiple times to figure out the problem). The response code should be included (because people have a tendency to copy and paste payloads but not headers when asking for help) and individual messages should include a link to documentation.

{
	"errorCode": "500",
	"messages": [{
		"message": "Field 'foobar' is not understood",
		"type": "Failure",
		"helpURL": "https://developer.somedomain.ext/people#fieldtypes",
		"txId": "127c4e701b9529cb92a9950a96c383ae",
		"path": "/people?fields=foobar,snafu",
		"timestamp": 1490222838
	}, {
		"message": "Field 'snafu' is not understood",
		"type": "Failure",
		"helpURL": "https://developer.somedomain.ext/people#fieldtypes",
		"txId": "127c4e701b9529cb92a9950a96c383ae",
		"path": "/people?fields=foobar,snafu",
		"timestamp": 1490222838
	}]
}