Status Codes

Every time you send a request to an API, it sends a response back. Part of that response is a status code, a three-digit number that tells you what happened. Did it work? Did something blow up? The status code tells you before you even look at the data.

Why Status Codes Matter#

Picture ordering food at a restaurant. The waiter could tell you one of a few things.

• "Here's your food!" (success)
• "We don't have that dish." (not found)
• "The kitchen is broken." (server error)

Status codes do the exact same job. They give you a quick summary of what went down.

The Five Categories#

Status codes are grouped into five categories by their first digit.

You'll mostly run into the 200s, 400s, and 500s. Those are the ones that matter day to day.

The Most Common Status Codes#

200 OK#

This is the one you WANT to see. It means everything worked.

GET /users/42
Status: 200 OK
 
Response: { "name": "Sarah", "email": "[email protected]" }

201 Created#

Something new got created. You'll see this after a POST request that worked.

POST /users
Status: 201 Created
 
Response: { "id": 43, "name": "Mike", "email": "[email protected]" }

204 No Content#

The request worked, there's just nothing to send back. You'll see it a lot after DELETE requests.

DELETE /users/42
Status: 204 No Content
 
Response: (empty)

400 Bad Request#

Something was off about your request. Maybe you forgot a required field, or you sent junk data.

POST /users
{ "email": "not-a-valid-email" }
Status: 400 Bad Request
 
Response: { "error": "Invalid email format" }

401 Unauthorized#

You're not logged in. The API has no idea who you are.

GET /private/data
Status: 401 Unauthorized
 
Response: { "error": "Please log in first" }

403 Forbidden#

You're logged in, you just aren't allowed to do this. Think of an employee trying to open the CEO's files.

DELETE /admin/settings
Status: 403 Forbidden
 
Response: { "error": "Admin access required" }

404 Not Found#

The thing you're looking for doesn't exist. This one's probably the most famous error code on the planet.

GET /users/99999
Status: 404 Not Found
 
Response: { "error": "User not found" }

You've definitely seen 404 pages on websites. Same idea. The page or resource just isn't there.

500 Internal Server Error#

Something broke on the server. This one's on them, so you can relax.

GET /products
Status: 500 Internal Server Error
 
Response: { "error": "Something went wrong" }

503 Service Unavailable#

The server is down or slammed. Try again later.

GET /products
Status: 503 Service Unavailable
 
Response: { "error": "Server is currently unavailable" }

Quick Reference#

Here's a handy list of the codes you'll bump into most.

How to Handle Status Codes#

When you're building apps, you check the status code to decide what happens next.

Step 1. Check for Success (200-299)#

If the code starts with 2, everything worked. Go ahead and use the data.

Step 2. Handle Client Errors (400-499)#

If the code starts with 4, something was wrong with the request. Show the user an error message. Maybe they need to log in, or fix what they typed.

Step 3. Handle Server Errors (500-599)#

If the code starts with 5, the server had a problem. Tell the user to try again later, since it isn't their fault either.

Reading Status Codes in Real Life#

When you're debugging an API problem, the status code is your first clue. Here's how I'd think through the usual suspects.

You get a 401. Check whether you included authentication. Are you logged in? Did you send an API key?

You get a 404. Check the URL. Did you spell it right? Does that resource actually exist?

You get a 400. Look at the data you sent. Is something formatted wrong? Are you missing a required field?

You get a 500. Not your problem. Wait a bit and try again... the server's having a rough day.

TL;DR#

• Status codes are three-digit numbers that tell you what happened
• 200s mean success
• 400s mean you made a mistake (client error)
• 500s mean the server made a mistake (server error)
• 200 OK is the most common success code
• 404 Not Found means the resource doesn't exist
• Status codes help you track down problems FAST

What's Next?#

You've learned about methods, endpoints, data formats, and status codes. So how do you prove who you are to an API? Next up is authentication, which covers API keys, tokens, and keeping your credentials safe.