1

So we have this hot discussion going on in the company about whether to put custom error codes in HTTP Header or in body. We Googled a lot but we couldn't come up with a definitive answer yet.

Here's the situation:

Team A Use HTTP error codes such as 401, 403 and 404 when an application error occurs and have the custom error codes and description in the body. (Examples of APIs doing this Stripe and Twitter)

Team B If a REAL HTTP errors occur, let the HTTP header be 401, 404 or whatever. Other than that, use HTTP 200 all the time, and if there are any application errors put it ONLY in the body. In other words, don't use HTTP Headers for application custom errors. (Example of API doing this Facebook)

Which one do you think is a best practice and why?

Thanks.

NarbehM
  • 345
  • 2
  • 13

3 Answers3

0

I would say neither is a real best practice, and it depends on what type of api design you're going for. If you are doing REAL REST, and not some kind of weak approximation, then team A is the only real choice. If Facebook does use 200 OK everywhere along with embedded error codes, then facebook deploys not a real REST service.

The point of REST is that if you do a GET request on something you will receive the full representation of that resource. If you do a GET request, and you receive a 200 OK along with an error in it's body, the implication is that you didn't actually do something wrong, but that that resource is a representation of an error... which is a bit odd, but I suppose it's not impossible.

Likewise, if I do a DELETE or PUT request, and I receive a 200 OK, the client must assume that the request was 100% successful. If the operation was unsuccessful, you must not return a 200-299 HTTP status code.

This is a best practice for REST, but REST is not the only paradigm. There's definitely other API styles that use HTTP more like a 'tunnel' to do RPC-like operations. Facebook does this, XML-RPC and SOAP are other examples but there's plenty of others to be found.

So the short answer is: If you do REST, then you must use proper status codes.

Evert
  • 93,428
  • 18
  • 118
  • 189
  • Thanks for your answer. Why do you think Facebook does HTTP 200 though? What's the philosophy in there you think? In addition, if neither are best practice, what is the correct way to do it ? – NarbehM Sep 29 '15 at 05:28
  • @N.M. I can't speak for facebook, so I don't know. But SOAP and XML-RPC do similar things, so it's not unprecedented. There's no 'correct' way to do this, as with many things. There's many schools of thought when it comes to API design. My preference is to use HTTP status codes the correct way, but I can't say that without acknowledging that other people don't feel that way. – Evert Sep 30 '15 at 10:54
0

With REST, HTTP shouldn't be considered only as a "transport" layer with you embed a protocol (the approach of SOAP). You have to leverage HTTP features like:

  • Resources
  • Methods
  • Status codes
  • Content negotiation
  • ...

A RESTful service needs to leverage HTTP status codes to tell the client if the request was successfully handled or not. There aren't REAL or not HTTP statuses.

For example:

  • With a status code 404, this means that the resource doesn't exist. For path like GET /contacts/1, this can correspond to the fact that no contact with id 1 is found in a database.
  • With a status code 400 or 422, this can mean that the provided data aren't correct. If you try to add a contact POST /contacts/ but you provide an email with a wrong format in the response payload { "email": "test" }.

But in addition, you can add some more details in the response payload. HTTP status can be too generic for your needs and the default message in HTML isn't really usable by the service caller. For example for a status code 400 or 422, you can have:

400 
{
  "messages": [
    {
      "field":"email",
      "message":"The format of the email isn't correct.",
      "type":"error"
    }
  ]
}

Perhaps this link could give some more hints: https://templth.wordpress.com/2014/12/15/designing-a-web-api/. See section "Handling errors".

Hope it helps you, Thierry

Thierry Templier
  • 198,364
  • 44
  • 396
  • 360
  • 1
    Thanks for the answer. The potential problem with this approach could be to distinguish between a real "HTTP 404" (meaning the one web server has generated) vs. the one we artificially generate in the code. In addition, how do you decide what HTTP error code to use for ambiguous cases; let's say do you use HTTP 204 or 404 for when a given resource ID does not return any value? – NarbehM Sep 29 '15 at 05:25
  • In fact, you should use the http status 204 when a request is valid but no data is returned. In fact, REST is based on the concept of resource. The associated state can be a file or something else (a row in a database). In fact, a web server provides an implementation for file system but the HTTP mechanisms aren't dependent of the implementation. For 404 with a GET, this simply means that the resource doesn't exist, not necessary that a file doesn't exist. Do you see the nuance? – Thierry Templier Oct 01 '15 at 08:39
0

Response Codes: RFC 2616 defines 41 HTTP response codes. Some of them are useless for our purposes, but collectively, they represent a basic set of semantics, defined in the most fundamental of all API standards. There’s no excuse for ignoring this gift. If you reinvent 404 (Not Found) or 409 (Conflict) for your API, you’re just creating more work for everybody. Use your response codes. If a client sends some bad data to your API, you should send the response code 400 (Bad Request) and an entity-body explaining what the problem is. Don’t send 200 (OK) with an error message. You’re lying to the client. You’ll have to write e

Refrence: Leonard Richardson, Mike Amundsen AND Sam Ruby RESTful Web APIs 2013. (http://www.amazon.com/RESTful-Web-APIs-Leonard-Richardson/dp/1449358063/ref=sr_1_1?ie=UTF8&qid=1443253687&sr=8-1&keywords=restful+api)

Arbi Bach
  • 1
  • 1
  • I think what you're saying makes sense. However, why do you think Facebook will have HTTP 200 for the error cases? What's the philosophy there? – NarbehM Sep 29 '15 at 05:21