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.
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
Because reading the RFC is only slightly more fun than putting on socks.
If you ever make up your own code,
Time for a live demo! We'll be using:
Now we'll dive into the codes themselves.
Unless you're making your own Chrome-competitor from scratch, you'll never need any of these.
Everything worked and you should feel happiness. Data is returned.
Same as 200, except acknowledgement that you created something new. Data is returned.
Your request worked fine, and there's nothing else to be said.
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.
"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.
Really should only be used when doing a POST and you're creating a document - this gives confirmation that it has been created.
"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.
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.
"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.
The endpoint that you're looking for is forever going to live at this new location.
The endpoint that you're looking for is temporarily going to live at this new location.
There was no new data to return.
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*
Ideal for times when the client has some cached content, and the server says that cache is fresh enough. Beyond query string parameters,
if-modified-since headers can also trigger this response.
"Yo SmartBot7000. What's the most recent tweet by @ecaron in the last two hours?"
HTTP/1.0 304 NOT MODIFIED
You tried something and the server didn't like it.
Access is denied, but you're not logged in so that might be why.
If your service requires $, you might want to send this.
Denied. Go away.
Don't know what you were asking for, it isn't here anyway.
|405||METHOD NOT ALLOWED
You're trying a
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.
The server doesn't want to talk to the client in the dialect the client chose.
|429||TOO MANY REQUESTS
Used for throttling.
Yes it is. 32 recognized errors, of which I think 10 are useful.
Which ones have people used?
|500||INTERNAL SERVER ERROR
You didn't plan for this to happen, did you?
You're trying a verb called
Server is either overloaded or down for maintenance.
The server can't talk to the place it looks for answers.
|505||HTTP VERSION NOT SUPPORTED
Client might be trying 2.0, but server only handles 1.1.
Something caused an infinite loop to happen.
|509||BANDWIDTH LIMIT EXCEEDED
Remember getting Slashdotted? Good times…
The line between the
Client and the
Server causing the error is blurred. And confusing. Here's my rule of thumb:
Although everyone loves getting a
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
500, double check to see if there's something better.
There probably is.
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.