Three Digits That Tell the Story

Every response you will ever receive leads with a three-digit number, and here is the mercy of the design: the first digit alone tells you most of the story. 2 means it worked. 3 means "elsewhere." 4 means the problem is on your side. 5 means it is on theirs. Four families, one glance.

Think of traffic lights. You do not memorize every intersection in Riverport; you know green, amber, red, and you read any crossing in the city at a glance. The first digit is the color. The last two digits are just the street name — useful when you need them, ignorable when you do not. (Strictly there is a fifth family, 1xx, that your tools handle for you and you can happily ignore.) This page installs the map; Chapter 7 walks the individual streets.

2xx: It Worked

The green family. 200 OK is the workhorse — asked, answered, here it is. Two siblings earn an early introduction: 201 Created, the specific success that follows a POST — "your new thing now exists" — and 204 No Content, success with deliberately nothing to say back, common after a deletion. A 204 confuses beginners into thinking something failed; it is the opposite. The server did the job so completely there was nothing left to report.

3xx: Go Elsewhere

The forwarding family. A 3xx says the thing you asked for lives at another address, and the response includes where. (One member means something else: 304 Not Modified, the cache's "nothing has changed since you last asked" — it returns in Chapter 8.) This is a redirect. Your browser follows them silently a dozen times a day — you never see the hop. The command-line tools of the next chapter are more literal: they show you the 3xx and wait for instructions, which is the right behavior for someone learning to see the seams. You will meet the flag that says "follow it" in Chapter 3.

4xx: the Problem Is on Your Side

The amber-going-red family, and the one you will get to know best — every beginner does. A 4xx means the request arrived, was read, and was refused for a stated reason: built wrong, missing a key, aimed at a room that does not exist. The crucial word is stated — a 4xx almost always comes with a body explaining itself, which makes this the most fixable family in the book. One preview, because you will meet it in Chapter 5: 401 means "who are you?" — the missing-key error, and the whole reason keys have a chapter.

5xx: the Problem Is on Theirs

The red family. A 5xx means your request was fine and the answering side failed anyway — the program crashed, the building is overloaded, the service is down for maintenance. The fix is never to edit your request; there is nothing wrong with it. The fix is patience, a status page, and — if it persists — an escalation with evidence. Chapter 7 turns that sentence into a routine.

And that is the whole chapter's promise kept. Address, request, response, verb, verdict: you can now read every part of the conversation two programs have when one asks the other for something. Next chapter, you stop reading and start sending.