Basic

The status number

I checked the body to see if a call worked. The status line already said it. The number is the verdict and the body is only the payload, so read the number first.

What you will see

400

About 1 min of reading

Try It

Read the status class of a few calls and blame the right side.

1

A good call returns 200. The class is success.

curl -s -o /dev/null -w "%{http_code}" https://api.example/users

Before you run it, say out loud what it will print. Then open the answer.

What it prints
200
2

A path that does not exist returns 404. The class is your fault, fix the path.

curl -s -o /dev/null -w "%{http_code}" https://api.example/nope

Before you run it, say out loud what it will print. Then open the answer.

What it prints
404
3

A malformed body returns 400. Still your fault, the request was wrong.

curl -s -o /dev/null -w "%{http_code}" -X POST -d 'not json' https://api.example/users

Before you run it, say out loud what it will print. Then open the answer.

What it prints
400

Data Flow

The status line carries a number whose first digit names the class: 2 success, 4 your fault, 5 server fault.
1 Server writes a status number
↓
2 First digit names the class
↓
3 2 is success, 4 is yours, 5 is theirs
↓
4 You act on the class
Why this works
The first digit is the class

2 success, 3 redirect, 4 your fault, 5 server fault. That one digit tells you who to blame. A 4xx you fix in the request, a 5xx you report to the service. Reading the class is faster than reading the phrase.

A 200 with a bad body

Some services return 200 with an error in the body. That is a design smell: the status lies. Trust the status when the service is honest, and when it is not, that dishonesty is a thing to report, not to work around silently.

Examples

Two hundreds

200 OK
201 Created

2xx means it worked. 200 is a plain success, 201 means a new resource was made. Both are green.

The four you wrote wrong

400 Bad Request
404 Not Found

4xx means your request was the problem. 400 is a malformed body, 404 is a path that does not exist. The fault is on your side.

The five on the server

500 Internal Server Error
503 Unavailable

5xx means the server broke. Your request may be perfect. A 500 is the server's own crash, not your typo.

Words this lesson uses

Each one is defined here on this site. Open the entry for the full definition and the other words it points at.

← GET versus POST
Previous Lesson
GET versus POST
Next Lesson
Headers describe the body
Headers describe the body →