consider expanding error messaging as per white house guide about http-api-design

[frankieroberto]

What are the benefits of having the HTTP response status also in the JSON, I wonder?

The Link to more information seems useful, although it being a comma-separated string rather than an array seems odd.

I'm not sure of the use-case for the userMessage – normally it's down to the developer to interpret error codes and present a user-interface, and I'm not sure I'd ever want to simply pass on a message from an API. Writing different messages for developers vs users seems like a bit of an anti-pattern too (as both should be equally clearly written).

[isleeponcouch]

The benefit I could see to having the HTTP status code in the JSON is that you don't have to breakout into the header data to get the code; it's there with the rest of your error data, but it probably is unnecessary overhead.

I'm not sure I understand the "Use three simple, common response codes", are they suggesting to use only 200, 400, 500 to the exclusion of more descriptive status codes like 201, 401, 507? If I'm reading that correctly then I can't see any reason for it, as a developer can choose to treat all 5 series status codes in the same way if they wish, while other developers may want to recover or behave in a different way based on the specific code returned. Providing a less descriptive code benefits neither.

[geemus]

Good feedback. I kind of liked the user vs developer messaging, as I've seen that sort of thing. At Heroku we might use user messages, for instance, in CLI responses or from the dashboard. Basically, that message is helpful if you have 3rd party users you are presenting info to. It makes sense to word it a bit different, basically you expect the developer might be able to change/do something about it, so instructing them on how to fix the issue makes sense. For a 3rd party user, however, you can often only explain simply and/or be apologetic. So kind of simple/apologetic vs complex/instructional or something.

I agree that the comma separated more-info is weird, though have a link of some sort there could be helpful (I'm not sure I would have a value handy for this purpose a lot of the time).

Including status there does seem a bit weird/redundant, I'd probably leave it out.

Similarly I think I prefer something like an error type string to just an integer to help developers know exactly whats up, ie unprocessable_entity or something, maybe even more specific like invalid_email in some cases. Basically the user shouldn't have to parse/compare against the developer/user strings (which might change) to figure out the specifics.

I'm definitely more of a fan of more status codes (where it makes sense to do so).

So, upon review, maybe I don't really like this example... I think it was probably at least helpful to dig in/consider/discuss though. What do you guys think?

[frankieroberto]

@geemus the usefulness of the HTTP integer codes is that you can do some reasoning with them, e.g. matching 5xx or 4xx to work out if it's a server error or client error (useful as a fallback if the code isn't in your list of expected ones).

[geemus]

@frankieroberto For sure. I guess I just didn't see value in having that in headers AND body, vs just headers. Does that make more sense?

[frankieroberto]

@geemus agreed – just using the headers seems most sensible to me (avoids the problem of the two codes accidentally contradicting each other).

[isleeponcouch]

@frankieroberto that's what I meant by overhead. Semantically I think it makes sense to leave it out also, the http header should provide enough information (i.e an appropriate status code) to determine there's been an error and the kind of error, the error message object is just an added convenience.

I definitely like the user and developer messages.