Your Friendly Neighborhood

HTTP Status Codes

Presented by Eric Caron / Made with Reveal.JS

What's a status code?

As defined in the 1996 IETF RFC-1945:

The Status-Code element is a 3-digit integer result code of the attempt to understand and satisfy the request. The Reason-Phrase is intended to give a short textual description of the Status-Code. The Status-Code is intended for use by automata and the Reason-Phrase is intended for the human user. The client is not required to examine or display the Reason-Phrase.

Wow. That was unpleasant.

Honestly, the 2014 HTTP/1.1 revision (RFC-7231) is a lot less painful.

The official list is maintained at http://www.iana.org/assignments/http-status-codes

We'll cover them from scratch anyway.

Because reading the RFC is only slightly more fun than putting on socks.

Let's play pretend!

You:

  • Have created an artificial intelligence application
  • Are not worried about it becoming SkyNet
  • Want to make people talk to it as a RESTful API
  • Plan to follow best practices for talking to it
  • Named it SmartBot7000, because the domain name was available.

FIRST RULE OF FIGHT CLUB HTTP STATUS CODES

If you ever make up your own code,
You are going to have a bad time

Where does that status code come into play?

Time for a live demo! We'll be using:

  • curl
  • http://httpbin.org/
    But first we'll take a moment to acknowledge how awesome httpbin is.

And that's how the web works.

Now we'll dive into the codes themselves.

High-level status code overview

  • 1xx - "Informational" (you'll never use this)
  • 2xx - "Successful" (you'll frequently use this)
  • 3xx - "Redirection" (you'll sometimes use this)
  • 4xx - "Client Error" (you'll frequently use this)
  • 5xx - "Server Error" (no comment)

Sidenote: I'm going to try focusing on the ones related to API communications. Twitter and Twilio serve as the basis for ones that are useful (though I'll expand if everything perks my interest.)

1xx Informational

Crickets chirp.

Unless you're making your own Chrome-competitor from scratch, you'll never need any of these.

2xx Successful

Code Meaning
200 OK
Everything worked and you should feel happiness. Data is returned.
201 CREATED
Same as 200, except acknowledgement that you created something new. Data is returned.
204 NO CONTENT
Your request worked fine, and there's nothing else to be said.

200 OK

Represents 99% of all successful conversations on the internet. Expected response for GET. Permissable response for all other verbs, though that's subject to debate.

Scenario

"Hey SmartBot7000, tell me your name."


HTTP/1.0 200 OK
Content-Type: text/plain; charset=utf-8

SmartBot7000. You could've come up with something better.
						

201 CREATED

Really should only be used when doing a POST and you're creating a document - this gives confirmation that it has been created.

Scenario

"Hey SmartBot7000, the capital of Iowa is Capital City."


HTTP/1.0 201 CREATED
Content-Type: text/plain; charset=utf-8

Good to know! I now know the capital of Iowa is Capital City.
						

204 NO CONTENT

Best for situations where you're deleting something and don't expect a change. When this happens in a web browser, they're not supposed to change the existing view.

Scenario

"Hey SmartBot7000, I was wrong about the capital of Iowa - delete it from your memory."


HTTP/1.0 204 NO CONTENT
						

Note: Use this one sparingly. People like to get data back, and it makes them sad when they don't.

3xx Redirection

Code Meaning
301 MOVED PERMANENTLY
The endpoint that you're looking for is forever going to live at this new location.
302 FOUND
The endpoint that you're looking for is temporarily going to live at this new location.
304 NOT MODIFIED
There was no new data to return.

301 & 302 Redirects…

This is great for browsers, but pretty confusing for APIs. If you have a properly versioned API, you should never be killing an endpoint. Stay away from this one in your API. *Cue Eric's confession*

304 NOT MODIFIED

Ideal for times when the client has some cached content, and the server says that cache is fresh enough. Beyond query string parameters, ETag and if-modified-since headers can also trigger this response.

Scenario

"Yo SmartBot7000. What's the most recent tweet by @ecaron in the last two hours?"


HTTP/1.0 304 NOT MODIFIED
						

4xx Client Error

Code Meaning
400 BAD REQUEST
You tried something and the server didn't like it.
401 UNAUTHORIZED
Access is denied, but you're not logged in so that might be why.
402 PAYMENT REQUIRED
If your service requires $, you might want to send this.
403 FORBIDDEN
Denied. Go away.
404 NOT FOUND
Don't know what you were asking for, it isn't here anyway.

4xx Client Error continued

Code Meaning
405 METHOD NOT ALLOWED
You're trying a GET, but the endpoint only supports a POST.
410 GONE
Should not happen in an API. Like a 404, except it acknowledges it used to exist.
415 UNSUPPORTED MEDIA TYPE
You tried to upload XML, but the server only recognizes JSON.
418 I'M A TEAPOT
An example that April Fools' jokes are both awesome and awful.
420 ENHANCE YOUR CALM
Popularized by Twitter, tells the client to slow down.

4xx Client Error continued

Code Meaning
426 UPGRADE REQUIRED
The server doesn't want to talk to the client in the dialect the client chose.
429 TOO MANY REQUESTS
Used for throttling.

That is a lot of Client Errors

Yes it is. 32 recognized errors, of which I think 10 are useful.

Which ones have people used?

400 401 402 403 404 405 406 407
408 409 410 411 412 413 414 415
416 417 418 420 422 423 424 426
428 429 431 444 449 450 451 499

5xx Server Error

Code Meaning
500 INTERNAL SERVER ERROR
You didn't plan for this to happen, did you?
501 NOT IMPLEMENTED
You're trying a verb called BLARKE? I don't know what that is.
503 SERVICE UNAVAILABLE
Server is either overloaded or down for maintenance.
504 GATEWAY TIMEOUT
The server can't talk to the place it looks for answers.

5xx Server Error continued

Code Meaning
505 HTTP VERSION NOT SUPPORTED
Client might be trying 2.0, but server only handles 1.1.
508 LOOP DETECTED
Something caused an infinite loop to happen.
509 BANDWIDTH LIMIT EXCEEDED
Remember getting Slashdotted? Good times…

5xx Server Error continued

The line between the Client and the Server causing the error is blurred. And confusing. Here's my rule of thumb:

  • If the client could have done something different to avoid an error, send a 4xx
  • Otherwise, send a 5xx

One More Note About 400 and 500

Although everyone loves getting a 200, 400 and 500 are generic and hard to compensate for. Although the attached "Response Status Message" provides insight, it isn't intended to be a programmatic-decision maker. These codes tend to become a catch-all and make long-term support difficult.

Whenever you are reviewing code and see a 400 or 500, double check to see if there's something better.
There probably is.

Resources

I could make up more, but that is really all you need. And they're both made by Runscope, and although this wasn't intentional it felt worthy of being acknowledged.

If you're a visual learner, though, you might want to check out http://httpstatusdogs.com/ or https://http.cat/. They give visual reminders - either in canine or feline flavors - of what the primary codes mean.