Lesson 4 of 12 · How the Web Talks
Status Codes
Understand HTTP status codes in plain English: the five groups, the codes you will meet most with APIs, and what your code should do for each one. With Python examples.
- 8 min read
- Beginner
- Reviewed
- What a status code is and where it appears
- The five groups of status codes
- The common codes you will meet when calling APIs
- How your program should react to each kind of code
Did it work?
Every response starts with a number that tells you, at a glance, how the request went.
The five groups
The first digit tells you the group. Once you know the groups, you can understand codes you have never seen before.
The codes you will meet most
| Code | Phrase | What it means for you |
|---|---|---|
200 | OK | it worked, the data is in the body |
201 | Created | your POST created something new |
204 | No Content | it worked, and there is nothing to send back |
301 | Moved Permanently | the endpoint has a new address |
400 | Bad Request | your request is wrong, such as a missing or invalid value |
401 | Unauthorized | you did not prove who you are: missing or wrong API key |
403 | Forbidden | the server knows who you are, but you are not allowed to do this |
404 | Not Found | there is nothing at this address |
429 | Too Many Requests | slow down: you sent too many requests too fast |
500 | Internal Server Error | the server crashed while handling your request |
502 | Bad Gateway | a server in the middle got a bad answer from another server |
503 | Service Unavailable | the server is overloaded or down for maintenance |
Python has every code built in, in the http module:
from http import HTTPStatus
for code in [200, 201, 404, 429, 503]:
status = HTTPStatus(code)
print(code, status.phrase)
print(HTTPStatus.NOT_FOUND.value)What should your code do?
The group decides your next step:
def next_step(code):
if 200 <= code < 300:
return "Success: read the data"
if code == 429:
return "Too many requests: wait, then try again"
if 400 <= code < 500:
return "Client error: fix the request, retrying will not help"
if 500 <= code < 600:
return "Server error: wait a little, then try again"
return "Unexpected code: log it and look into it"
for code in [200, 201, 400, 401, 404, 429, 500, 503]:
print(code, "->", next_step(code))Notice that 429 is checked before the general 4xx rule. It is the one client error where waiting and retrying is the right answer.
Real status codes
Here are real servers answering with different codes. The second request asks Open-Meteo for an impossible latitude, and the third asks for a post that does not exist:
from http import HTTPStatus
import requests
checks = [
("Good weather request", "https://api.open-meteo.com/v1/forecast", {"latitude": 17.38, "longitude": 78.49, "current": "temperature_2m"}),
("Impossible latitude", "https://api.open-meteo.com/v1/forecast", {"latitude": 500, "longitude": 78.49, "current": "temperature_2m"}),
("Missing blog post", "https://jsonplaceholder.typicode.com/posts/99999", {}),
]
for label, url, params in checks:
response = requests.get(url, params=params, timeout=10)
print(f"{label}: {response.status_code} {HTTPStatus(response.status_code).phrase}")
if response.status_code == 400:
print(" The server explains:", response.json()["reason"])A good API does not just say "400". It also explains the problem in the body, so read the body when something goes wrong.
The ok shortcut
You will often see this pattern:
if response.ok:
data = response.json()
else:
print("Request failed with status", response.status_code)Common mistakes
Write the function every API client needs: one that sorts a status code into its group.
# Write a function category(code) that returns:
# "success" for 200 to 299
# "redirect" for 300 to 399
# "client error" for 400 to 499
# "server error" for 500 to 599
# "unknown" for anything else
for code in [200, 204, 301, 401, 404, 429, 500, 503, 999]:
print(code, category(code))
# Output must be exactly:
# 200 success
# 204 success
# 301 redirect
# 401 client error
# 404 client error
# 429 client error
# 500 server error
# 503 server error
# 999 unknown
Your request returns 401 Unauthorized. What is the most likely cause?
Summary
- Every response starts with a status code. The first digit gives the group.
- 2xx success, 3xx redirection, 4xx a problem with your request, 5xx a problem on the server.
- Common codes: 200, 201, 204, 400, 401, 403, 404, 429, 500, 503.
- Fix the request for 4xx errors. Wait and retry for 5xx errors and for 429.
- Always check the status before using the body.
You have finished the first module. Next: JSON, the format almost every API uses for its data.
Finished reading? Tick it off to track your progress.