Creating custom status codes

Question

I'm having an API on which I need to set custom status code. Apart from the normal standard http status codes, is it the best practice to create our own status code?

i.e, If my client is sending a blank parameter (orderID), can I set a random status code number of my own say 123? Or is there any standard way to create customer status codes?

Answer 1

There are quite a lot of existing codes, so usually you won't need to invent new ones. You might, though, but when you do, make sure to use the right ranges.

For instance, the 200+ range indicates success of any kind, 300+ is a redirect, 400+ range is a client error (bad url format, target not found), and 500+ is a server error.

By following these guidelines, you can use all kinds of clients to communicate to your api. A browser should normally display the results of any 2XX status code, and treat it as a succesful request, even if the particular XX is unknown to it.

For a rather complete list of status codes and their normal meaning, as well as a general description of each of the ranges, see this: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

599 is the highest assigned status code. I wouldn't know if it's allowed to use the 600+ range, but I cannot find anything about it. I cannot imagine that your status wouldn't fit in any of the existing categories, though.

REST: Aside from the return code, you can (should?) also have a look at the different methods. You probably know GET (sending data in url) and POST (sending extra data with the request), because they are commonly used. But you also got PUT and DELETE, which are especially useful for an api like this. If you search for terms like Restfull API, you should get plenty of documentation about this subject. Also, see this W3 link for an overview of request methods.

Bringing it together: For creating a customer through the api, you could send a PUT request with the data of the new customer. The api can return 201 Created with an ID (or slug) for the customer. If you want to delete the customer, send a DELETE request and return 204 No content, since you just need to confirm that the delete succeeded, without sending any content.

Answer 2

Or is there any standard way to create customer status codes?

No. I'd go for a generic HTTP error as 400 Bad Request and provide a meaningful error message in the response body. This wasy you don't have to make up HTTP codes as you go, and your consumers can process different error responses identically.

Answer 3

Don't define custom status codes unless you're willing to going through the process of standardizing them (http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p2-semantics-26.html#considerations.for.new.status.codes).

Otherwise just use a generic one and send additional details in the response body.