How to handle REST Exceptions?

Question

We are in the middle of a ongoing discussion about how to handle REST exceptions.

Response Content type : JSON

Two solutions we have:

1. Throw all the unchecked exceptions as a JSON response.
2. Send Request Invalid Response code.

Arguments:

• When its a error, why return JSON? Just send a invalid response code.

Counter Argument:

• Response code are too technical to handle for normal developers.

Whats your say??

Bartholemy

I wonder why response codes are too technical. If you have to/can take any corrective action you should depend on the response code (or any other error code inside the json) and not on user readable error strings – Compeer

We deal with all kinds o clients. So we dont want to assume that the developers with the clients are proficient enough to understand the response codes. That was few people's thoughts and mine too. If they look at the json they can understand the error. – Bartholemy

One of the major advantages of REST is uniformity of interfaces. So when you say we have a REST api, the client automatically anticipates list of resources and the GET PUT POST DELETE operations and similarly he knows about the error codes that he can imagine. Error strings would definitely be useful for your client (developers) to debug. But the code they write against your api should take actions based on the codes and not strings. – Compeer

Answer 1

For a JSON API I recently developed I do both. I always respond with valid JSON (well, assuming I respond at all). If I detect an invalid request, I use status 400. If I detect a server error (which I don't believe is caused by an invalid request), I use a 5xx status. The JSON object contains a special key that is only set for errors, with a string value.

I think this is a good solution that respects REST principles, and can be used in multiple ways. The same solution is used by some other JSON APIs, such as Yahoo Search. Try http://search.yahooapis.com/ImageSearchService/V1/imageSearch?appid=YahooDemo&output=json .

Schoolmate

+1: With a RESTful use of HTTP you absolutely must leverage HTTP response codes. Additional information can be returned in the representation. – Herschel

I just saw this answer in SO's "Related" items. And although its an old answer it's obviously still showing up. I believe there is a lot more to good error handling than simply using the HTTP status codes (which is a good start though!). See soabits.blogspot.dk/2013/05/… for an in depth discussion. – Mimicry

Answer 2

Use error codes like for HTTP. So 50* for any exception cause by some internal problem. And 40* for bad arguments. Avoid using your own defined codes as far as its possible. The idea is to have a "uniform" interface.

In general. 204 for success without sending any content 200 for success with a json representation of the resource And if its not a successful operation return appropriate response code. You can choose to optionally return a json. To simplify things you can have a common format (json) for all error responses.

http://en.wikipedia.org/wiki/REST is a must read before you freeze on your api specs.

Compeer

"201 for success without sending any content." 201 is created, so it should only be used when "a new resource [is] created", not for general success. You might be thinking of 204, "No Content" – Schoolmate

Answer 3

For the developers consuming your REST it is helpful to provide as much information as needed but not more than that. You don't want to disclose too much information on your infrastructure do you? So you might want to distinguish between:

• Bad parameters: 400 Bad Request
• Resource not available: 404 Not Found
• Not authorized: 401/403: Unauthorized
• Internal: 500 Internal Server Error
• Empty: 200 OK
• Empty: 204 No Content

If an endpoint does not exist this would be a 404, if some internal system, e.g. a database is down or database logon fails a 500 and if the URI is not found a 404, 200 or a 204 (the debate is ongoing) but I prefer a 200 with an empty result for a URI representing a list of resources being empty but a 404 when a specific resource was required and not located. In all these cases you might provide a different body message helpful to the developer on the consumer end.

So you might want to distinguish exactly what exception occurred: an upstream error reporting is useless to the consumer, e.g. database errors, or an interface error which is very relevant to the consumer, like a query string containing unknown attributes.

Rhotacism