> What if there were two reasons to forbid the request?
Just return the first. Most languages only have support for one error at a time (think exceptions in Python/C++/Java/C#/…, return codes in C) so returning more than one error ends up being really difficult to an API: what do you do? Raise some sort of MultipleErrors exception? (then how do you catch this?); take the first? (what was the point of multiple, then?)
The same complexity exists on the server-side: you have to maintain some sort of "errors thus far" state, instead of just doing what is probably the language-natural thing: raise an exception that'll get translated to JSON.
The only real case I've found for multiple errors is form-field validation, when multiple fields don't validate. I've found it's sufficient to just bottle them into a "ValidationError" and return that: it can contain a list of fields and their issues. The rest of the API can then continue to benefit from a simpler interface.
Return the error for the problem that occurs first, or - in the case of dependent errors - concatenate the problems in one error. Would be my suggestion.
See 3.2: "extension members". A reason phrase from the HTTP response can't contain structures which are easily parsed, this proposal does make this possible.
We are using this format for quite some time and it is very easy to use. In above example "Not Enough Credit" sounds reasonable, but you often want to inform users with more information: what was the transactional amount, what is the balance, are there other reasons the transaction failed? You can easily extend the response with more fields to indicate such thing.
Besides, you can track any error in your backoffice system and link the error number in your response. This allows you to have direct insights in error history for customer support ("Hey I got an error and the system said to report number 23473 to you, can you help me?").
It doesn't preclude putting computer-readable data in the body of the response.
Their example is the error 'You do not have enough credit'. Surely their web server should be sending '403 You do not have enough credit' and not '403 Forbidden' ?
I like the idea but I wonder how it plays together with "human-friendly" APIs that return error codes and HTML. Should you use Accept: headers to signify that you want a machine-readable error message?
You could definitely use content negotiation to present human-friendly errors if you were exposing HTML out of the API itself. But otherwise the concept of "human friendly" APIs seems a little weird to me. Likewise, the idea that error codes are more friendly than links to error entities also seems way more developer- / human-friendly. Random per-application error codes seem like a really bad idea to me, if you have the need to expose more information about a group of errors, the right way seems like this approach - link to a common error object, which itself contains classification details
You are right that this is no good idea in the general case. But I think there are a few endpoints that have "pretty printing" outputs for developers enabled if text/html is in the accept list. At least the (internal) deviantart API did have that some time ago.
I agree that the whole thing can be solved nicely with content negotiation.
