API FUNDAMENTALS / LESSON 05
Status Codes.
Understanding API responses
Loading the lesson…
Loading activities…
Browse lessons
API FUNDAMENTALS / LESSON 05
Understanding API responses
Loading the lesson…
Loading activities…
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.
Picture ordering food at a restaurant. The waiter could tell you one of a few things.
Status codes do the exact same job. They give you a quick summary of what went down.
Status codes are grouped into five categories by their first digit.
| Code Range | Category | Meaning |
|---|---|---|
| 100-199 | Informational | "I got your request, still working..." |
| 200-299 | Success | "Everything worked!" |
| 300-399 | Redirect | "Go look somewhere else." |
| 400-499 | Client Error | "You made a mistake." |
| 500-599 | Server Error | "I made a mistake." |
You'll mostly run into the 200s, 400s, and 500s. Those are the ones that matter day to day.
This is the one you WANT to see. It means everything worked.
Something new got created. You'll see this after a POST request that worked.
The request worked, there's just nothing to send back. You'll see it a lot after DELETE requests.
Something was off about your request. Maybe you forgot a required field, or you sent junk data.
You're not logged in. The API has no idea who you are.
You're logged in, you just aren't allowed to do this. Think of an employee trying to open the CEO's files.
The thing you're looking for doesn't exist. This one's probably the most famous error code on the planet.
You've definitely seen 404 pages on websites. Same idea. The page or resource just isn't there.
Something broke on the server. This one's on them, so you can relax.
The server is down or slammed. Try again later.
Here's a handy list of the codes you'll bump into most.
| Code | Name | What It Means |
|---|---|---|
| 200 | OK | Request succeeded |
| 201 | Created | New resource created |
| 204 | No Content | Success, but no response body |
| 400 | Bad Request | Your request was wrong |
| 401 | Unauthorized | You need to log in |
| 403 | Forbidden | You don't have permission |
| 404 | Not Found | Resource doesn't exist |
| 500 | Internal Server Error | Server crashed |
| 503 | Service Unavailable | Server is down |
When you're building apps, you check the status code to decide what happens next.
If the code starts with 2, everything worked. Go ahead and use the data.
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.
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.
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.
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.