REST and HTTP: A Visceral Guide to Status Codes

I was in an argument … er … discussion here, and we couldn’t agree on the usage of a couple of the 40x HTTP error codes. So I spun out a quick email putting a more colloquial spin on the codes in question. It did help move the conversation along.

One of the tenets of REST is to use a uniform interface. So if you are putting a REST service on top of HTTP, it’s really important that you *use* HTTP, and use it *correctly*. So the HTTP status codes become very important, and you shouldn’t neglect them like I did in the first 20 years of my programming career.

So here’s a visceral guide to the HTTP status codes, also known as The Dude’s Guide to HTTP status codes. Or Dudette’s.

I marked the ones you mostly have to worry about with a “(!)”.

10x The spec defines codes in this range, and then tells you not to use them. Thanks.

The 200 codes are used to make the client feel warm, safe and happy. Only use these codes if the operation succeeded. Or if it’s your boss and reviews are coming up.

(!) 200 OK Like, yeah!

(!)201 Created Yeah I made it for you.

202 Accepted Yeah, Riiiiiiiiiiiiight. You bet. Mmm-hmm.

-or- 202 Accepted No problem, I’m on it.

204 No Content (silence is consent)

-or- 204 No Content Yeah, OK, here it is but there’s nothing in it.

The 300 codes start to get into scary territory, not because anything is specifically wrong, but because it’s not immediately clear it’s all right. Also, the 300 codes sometimes mean more work for the client, which could upset them because of all the work they’ve done to get here already.

300 Multiple Choices Well, there are several places you can find that. Let me make you a list.

(!) 301 Moved Permanently Nope. Try over here. And don’t come back. Ever.

302 Moved Temporarily Yeah, look over there. But it might come back, so check here later.

302 er… BTW don’t use 302. This is good for web pages and overly-complicated protocols, but for “resources”, if it’s moved, it’s probably gone for good.

304 Not Modified Yeah, no changes. Keep using the one you have.

400 codes are frought with peril, because now you’re just telling the client they are wrong, or have messed up. That’s always scary. But be brave, because these codes mean someone else has failed.

400 Bad Request What? I mean… really, what?

(!) 401 Unauthorized Nope, not until I know who you are.

-or- 401 Unauthorized I don’t see you on the list.

402 What Happened to 402? poor 402

(!) 403 Forbidden No way, not now, not ever. And I don’t care who your daddy is.

(!) 404 Not Found What? There’s nothing like that here.

Now the territory gets treacherous. The 500 codes are areas where we start admitting fault. And you know what admitting fault leads to — lawsuits.

(!) 500 Internal Server Error Wow. That really didn’t work.

501 Not Implemented Um, let me see. No, we haven’t done that one yet.

502 Bad Gateway I’d like to have an answer for you, but you know what? I just don’t. Maybe the guy down the line will have an answer next time you ask.

503 Service Unavailable Wow, we are super-duper busy right now. Mind checking back later? Well, check back later anyway.


Leave a comment

Filed under REST

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s