HTTP Status Codes Cheat Sheet (1xx-5xx Explained)
· 6 min read
Every HTTP response carries a status code, and choosing the right one is part of designing a good API. The codes are not arbitrary - they fall into five classes, each with a clear meaning, and getting them right makes your API predictable for the clients and developers who consume it.
The Five Classes
The first digit tells you the category. 1xx is informational, 2xx means success, 3xx means redirection, 4xx means the client made a mistake, and 5xx means the server failed. That split - client error versus server error - is the most important distinction in the whole scheme, because it tells the caller whether retrying or fixing their request is the right move.
1xx Informational
You will rarely set these yourself. 100 Continue signals that the client may send the request body, and 101 Switching Protocols is used during WebSocket upgrades. Frameworks handle these for you.
2xx Success
This is where you spend most of your time. 200 OK is the everyday success response for a request that returns data. 201 Created is the correct response when a request creates a new resource, such as a POST that inserts a record; include a Location header pointing at the new resource. 204 No Content means success with no body to return, which is ideal for a DELETE or an update where the client does not need the result echoed back.
3xx Redirection
301 Moved Permanently tells clients and search engines that a resource has a new home for good, and they should update their links. 302 Found is a temporary redirect, used when you want to send the client elsewhere now without implying the change is permanent. 304 Not Modified is the workhorse of caching: when a client sends a conditional request and the resource has not changed, you return 304 with no body, and the client reuses its cached copy. That saves bandwidth on every repeat request.
4xx Client Errors
These are the most nuanced and the most commonly misused. 400 Bad Request means the request was malformed - invalid JSON, a missing required field at the syntax level. 401 Unauthorized actually means unauthenticated: the client has not proven who it is. 403 Forbidden means the client is authenticated but not allowed to do this. 404 Not Found means the resource does not exist. 409 Conflict signals that the request collides with the current state, such as a duplicate unique key or an edit against a stale version. 422 Unprocessable Entity is for requests that are syntactically valid but fail business validation - the JSON parsed fine, but the email address is already taken. 429 Too Many Requests is your rate-limit response; pair it with a Retry-After header so clients know when to come back.
The 401 versus 403 confusion is the classic one. Authentication is who you are; authorization is what you may do. Use 401 when credentials are missing or invalid, and 403 when valid credentials lack permission.
5xx Server Errors
500 Internal Server Error is the catch-all for an unhandled exception on your side - something broke and it is not the client's fault. 502 Bad Gateway means a server acting as a proxy got an invalid response from upstream. 503 Service Unavailable means you are temporarily down, overloaded, or in maintenance; like 429, it can carry a Retry-After header. The crucial point with 5xx codes is honesty: do not return 200 with an error message in the body, because clients and monitoring tools rely on the status code to detect failure.
Keep a Reference Handy
Nobody memorizes all of them, and you do not need to. When you hit an unfamiliar code in a log or a response, the HTTP Status Codes reference gives you the meaning and the typical use case at a glance, so you can pick the correct one instead of defaulting to whatever is nearest to hand.
Quick Decision Guide
- Created something? 201. Nothing to return? 204. Otherwise 200.
- Not logged in? 401. Logged in but blocked? 403. Does not exist? 404.
- Bad syntax? 400. Valid syntax, failed validation? 422. State conflict? 409.
- Too many requests? 429 with Retry-After.
- Your bug? 500. Upstream bad response? 502. Temporarily down? 503.