Best way to return error messages on REST services?

Question

I've been looking at examples of REST API's like Netflix http://developer.netflix.com/docs/REST_API_Reference#0_59705 and Twitter and they seem to place error messages in the statusText header response instead of the responseText. We're developing an internal RESTful api and I am arguing for sending custom statusText messages and ignoring the responseText.

For the scope of our app, we're returning error 400 when the user has tried doing something they aren't supposed to, and the only error messages that will be updated in the UI for the user will be delivered with 400. I am of the belief that the message should be sent as a modified statusText but one of the engineers (who knows a bit less about REST than me) is arguing for sending it in the responseText.

What's the best way to go?

Answer 1

I think you're right, the general approach is use the existing error mechanism built into HTTP.

In general, try to map your errors to existing HTTP errors, for example if they request something they don't have permission to, return a 403 error.

If they request something that doesn't exist, return a 404.

• Alex

Answer 2

HTTP defines that you should put a descriptive error message in the response entity body, aka responseText.

statusText is not rendered or processed by any client.

I'd use the status text for the error message type, aka 400 Client Error, and the body for a description of the problem that can be rendered to the user, in whatever the format the client may be able to process.

Answer 3

Picking appropriate status code for your responses is extremely important as it is a key enabler of self-descriptive messages.

The entity body should be a representation of the resource's state and ideally contain hyperlinks to available next states in your application