The five classes of status codes
HTTP status codes are grouped into five classes based on the first digit. 1xx codes are informational — they indicate a provisional response. 2xx codes indicate success. 3xx codes indicate redirection — the client needs to take another action to complete the request. 4xx codes indicate client errors — something wrong with the request. 5xx codes indicate server errors — something wrong on the server's side.
The first digit immediately tells you who is responsible for the problem. A 4xx code means the client (usually your code or the user) sent a bad request. A 5xx code means the server failed to process a valid request. This distinction matters enormously for debugging.
- 1xx — Informational (100 Continue, 101 Switching Protocols)
- 2xx — Success (200 OK, 201 Created, 204 No Content)
- 3xx — Redirection (301 Moved Permanently, 302 Found, 304 Not Modified)
- 4xx — Client Error (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity, 429 Too Many Requests)
- 5xx — Server Error (500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout)
The most important codes explained
200 OK is the standard success response. The request succeeded and the response body contains the requested data. 201 Created is used when a POST request successfully creates a new resource — the Location header usually points to the new resource's URL. 204 No Content means the request succeeded but there's no body to return — common for DELETE requests.
301 Moved Permanently tells the client and search engines that the resource has permanently moved to a new URL. Search engines transfer SEO equity to the new URL. 302 Found is a temporary redirect — search engines should keep the original URL indexed. 304 Not Modified tells the client the cached version is still valid, saving a full download.
401 Unauthorized means the client is not authenticated. 403 Forbidden means the client is authenticated but doesn't have permission. 404 Not Found means the resource doesn't exist at this URL. 429 Too Many Requests means the client is being rate-limited.
Status codes in API design
Choosing the right status code is part of designing a good REST API. Using 200 for everything — including errors — makes clients unable to detect failures programmatically. The HTTP spec exists precisely so clients know how to handle responses without reading the body first.
A common debate is 401 vs 403. Use 401 when the client isn't authenticated at all (send credentials). Use 403 when the client is authenticated but isn't allowed to access this resource (the credentials are valid but the permissions aren't sufficient).
For validation errors, 422 Unprocessable Entity is the most semantically accurate code — the request was well-formed but the content was invalid. Some APIs use 400 Bad Request for both malformed requests and validation errors; 422 is more precise.