Velamuvi AIAcademy

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
In this lesson you will learn
  • 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

CodePhraseWhat it means for you
200OKit worked, the data is in the body
201Createdyour POST created something new
204No Contentit worked, and there is nothing to send back
301Moved Permanentlythe endpoint has a new address
400Bad Requestyour request is wrong, such as a missing or invalid value
401Unauthorizedyou did not prove who you are: missing or wrong API key
403Forbiddenthe server knows who you are, but you are not allowed to do this
404Not Foundthere is nothing at this address
429Too Many Requestsslow down: you sent too many requests too fast
500Internal Server Errorthe server crashed while handling your request
502Bad Gatewaya server in the middle got a bad answer from another server
503Service Unavailablethe server is overloaded or down for maintenance

Python has every code built in, in the http module:

Try it yourselfPython
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:

Try it yourselfPython
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:

Try it yourselfPython
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

Practice exercise

Write the function every API client needs: one that sorts a status code into its group.

Your solutionPython
# 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
Knowledge check

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.