The status code is the first thing to read in a response. It tells you what happened, in a way that any HTTP client can understand without knowing your API.
Five classes
The first digit gives the class:
| Class | Meaning | What to do |
|---|---|---|
1xx |
Informational | You'll rarely see these |
2xx |
Success | Carry on |
3xx |
Redirection | Look somewhere else |
4xx |
Client error | Change the request before sending it again |
5xx |
Server error | The request may be fine; the server has a problem |
If a client sees a code that it doesn't know, it can treat it as the x00 code of that class. So a client that doesn't know 418 still knows that it's a client error.
2xx: it worked
| Status | Use |
|---|---|
200 OK |
The request worked, and the response has the result |
201 Created |
A new resource was created; Location gives its URL |
202 Accepted |
The work has been accepted, but isn't finished yet |
204 No Content |
The request worked, and there's no body |
You've already seen 200, 201, and 204 from the Contacts API.
3xx: look elsewhere
This request uses http, but the server wants https:
The status is 301 Moved Permanently, and the location header has the new URL. By default, curl doesn't follow redirects, and neither do the cells in this course. In your terminal, add -L to follow them.
| Status | Use |
|---|---|
301 Moved Permanently |
Use the new URL from now on |
302 Found |
Use the new URL just this time |
304 Not Modified |
Your cached copy is still good |
4xx: fix your request
Produce each of these yourself. Read the status and the body each time.
400 Bad Request: the server can't accept what you sent.
404 Not Found: there's no such resource.
405 Method Not Allowed: this URL doesn't support this method.
415 Unsupported Media Type: the server can't read the format of the body. Without -H, curl says that the body is form data.
A few more that you'll meet in other APIs:
| Status | Use |
|---|---|
401 Unauthorized |
Authentication is missing or invalid: who are you? |
403 Forbidden |
We know who you are, and you can't do this |
409 Conflict |
The request conflicts with the current state of the resource |
422 Unprocessable Content |
The syntax is fine, but the content can't be processed |
429 Too Many Requests |
Slow down |
Despite its name, 401 is about authentication, and 403 is about authorization. We'll come back to these in a later chapter.
5xx: it's not you
| Status | Use |
|---|---|
500 Internal Server Error |
Something went wrong on the server |
502 Bad Gateway |
A proxy got a bad response from the server behind it |
503 Service Unavailable |
The server is overloaded or down for maintenance |
504 Gateway Timeout |
A proxy didn't get a response in time |
A 4xx usually fails again unless you change the request. A 5xx might work if you try again later, as long as the request is safe to repeat.
When an API ignores status codes
Our course has a second version of the Contacts API, in an older RPC style. Ask it for a contact that doesn't exist:
The status is 200 OK, even though the call failed. The failure is only in the body.
Discuss: A monitoring tool counts the
5xxand4xxresponses from each API. What will it report for this API? What must each client of this API do to detect a failure?
Summary
- Read the status code first, starting with its class.
4xxmeans that the client needs to change something, and5xxmeans that the server has a problem.- Use real status codes in your own APIs, because every HTTP tool understands them.
Next, we'll look at headers.