Problem Details for HTTP APIs

multipart/alternative? :)

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.

Maybe this needs to be wrapped in a "application/problem-collection+json" specification ;-)

> 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.

Strictly speaking, they can, but then you're parsing strings to figure out what exactly is wrong...

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?").

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