Introduction
HTTP status codes tell the client whether a request succeeded, failed, and why. They’re part of every API and web response. Below we run through the ranges and the codes you’ll see most often. Use them right and you get better caching, clearer error handling, and APIs that behave the way clients and tooling expect.
What Is Understanding HTTP Status Codes
An HTTP status code is a three-digit number returned in the first line of the response (e.g. 200 OK, 404 Not Found). The first digit defines the class: 1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error. The rest refine the meaning. Codes are defined in the HTTP spec and in extensions (e.g. 208, 429). The status line is the first line of the HTTP response (e.g. HTTP/1.1 200 OK). Optional reason phrases (e.g. OK, Not Found) can be overridden by servers but are often ignored by clients, which rely on the numeric code.
Why It Matters
Clients use status codes to decide what to do: retry, show an error, follow a redirect, or cache. APIs that return 200 for everything force clients to parse the body to detect errors, which breaks caching and standard handling. Using the right codes makes clients and tooling behave correctly.
How to Calculate It
| Range | Category | Code count |
|---|---|---|
| 100–199 | Informational | 100 |
| 200–299 | Success | 100 |
| 300–399 | Redirection | 100 |
| 400–499 | Client Error | 100 |
| 500–599 | Server Error | 100 |
Real-Life Example
GET /users/999 when the user doesn’t exist: return 404 and maybe a body like {"error": "User not found"}. POST /users with invalid email: return 400 and validation details. After login, return 200 with a token or 401 if credentials are wrong. The client checks response.status (or equivalent) before parsing the body.
Common Mistakes
Returning 200 for errors and putting the error only in the body. Using 500 for validation errors (use 400). Using 404 when 403 is more accurate (resource exists but the user can’t access it). Returning 3xx without a Location header. Using non-standard codes without documenting them.
Practical Tips
- Use 2xx for success, 4xx for client mistakes, 5xx for server failures.
- Return a consistent error body (e.g. code, message, details) with 4xx/5xx.
- Use 201 for creation and set Location to the new resource when appropriate.
- Use 429 (Too Many Requests) for rate limiting with Retry-After if possible.
- Document which codes your API returns and when.
FAQs
Conclusion
Status codes are the standard way to signal result and failure. Use 2xx/4xx/5xx consistently, return a clear body for errors, and document your API. Clients and tooling will work better for it.