Decide by Class First

get_json returns whatever status arrived. On the first page of items that is 200, but the same function returns a 404 for an item that does not exist, a 429 when you ask too often, and a 504 when a server further along gives up. A client needs a rule for what to do next, and that rule cannot be a list of every code: there are dozens, new ones get defined, and a server may send one your client was never written for. HTTP puts the rule into the code itself, in its first digit.

Five classes

A status code is three digits, and the first one names its class:

The class answers the first question every client has: did it work, and if not, whose move is it? A 4xx says the next move is yours, because the server will not act until something about the request, or when you send it, changes. A 5xx says the server failed; your request may have been fine. The exact code adds detail inside the class. A 404 says the thing you asked for is not there, 401 and 403 are about who you are and what you may do (Chapter 7 tells them apart), and 301, 307, and 308 say how a redirect should be followed (Chapter 6).

Why the class comes first

HTTP’s definition (RFC 9110, section 15) asks every client to understand the class of any code, and to treat a code it does not recognize like the x00 code of its class. A client that has never heard of 299 treats it as 200, and one that has never heard of 451 treats it as 400. So a client that decides by class first is never stuck: it has an answer for every code, including codes invented after it was written. It can still look at the exact code afterward, as it will for 429.

Finding the class takes one operation you know from Python Fundamentals: floor division by 100 drops the last two digits. Once you have the class, one comparison answers “did it work?”:

Only 204 prints True: it is the one success among the four, even though it carries no body.

What raise_for_status did

In Python in Practice, response.raise_for_status() turned every 4xx and 5xx into an exception before your code decoded the body. That is the class rule in its shortest form: success or not. It has a cost: your code never decoded the error body. An error body often says what was wrong, such as which parameter was out of range, and a client that raises before looking at it throws that away. Lesson 4 keeps the body of every response and attaches the class to it instead.

for code in [101, 304, 451, 500]:
    print(code, code // 100)

You now have a rule for any status. Some decisions need more than the status, such as how long to wait after a 429, and that information arrives in the response headers. The next lesson reads them.