An HTTP status code is a three-digit number the server returns to summarize how it handled the client's request. It sits on the first line of every HTTP response — the status line — alongside a short reason phrase, such as 200 OK or 404 Not Found. The reason phrase is a human-readable hint only; programs make decisions based on the numeric code, not the text.
The five classes
Codes are grouped into five classes by their first digit. The design lets you grasp the general outcome from that digit alone, so even an unfamiliar code carries meaning at a glance.
- 1xx (Informational): A provisional response — the request was received and processing continues.
100 Continue,101 Switching Protocols. - 2xx (Success): The request was received, understood, and accepted.
200 OK,201 Created,204 No Content. - 3xx (Redirection): Further action is needed to complete the request, usually following a different URL.
301,302,304 Not Modified. - 4xx (Client Error): Something is wrong with the request itself — bad syntax, missing auth, unknown resource.
400,401,403,404. - 5xx (Server Error): The request was fine but the server failed to fulfill it.
500,502,503.
Reading a status line
A status line has the form HTTP-version status-code reason-phrase. Here is a typical response as shown by curl -i:
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 42
{"error":"user not found","id":"u_92311"}The key habit is to read the leading digit first. A 4 means the client's request is at fault; the trailing 04 narrows it to 'the target resource does not exist.' Before blaming the server, suspect a wrong URL or identifier.
Quick rules for debugging
- You got 2xx but the result looks wrong → Suspect the response body or business logic, not the transport. The exchange itself succeeded.
- 4xx → Fix your request. Check the URL, method, headers (especially
AuthorizationandContent-Type), and body format. - 401 vs 403 → 401 means 'I don't know who you are (authenticate)'; 403 means 'I know who you are, but you're not allowed.'
- 5xx → It's the server's problem. Retrying can help for 502/503/504, and you should read server logs.
- 3xx → Follow the
Locationheader to see where you're being sent. Redirect loops and endless http→https bounces are common traps.
Because status codes are a shared vocabulary defined by the standard (RFC 9110), clients and servers can communicate without knowing each other's internals. That said, many APIs bend the semantics, so treat the code as a first signal and always read the detailed error message in the body.