What is an HTTP status code?
HTTP stands for HyperText Transfer Protocol. It is the foundation of data exchange on the web: every time your browser loads a page or your app calls an API, it sends an HTTP request and receives an HTTP response.
Every HTTP response begins with a three-digit status code followed by a short reason phrase. The code tells the client what happened to its request: did it succeed, was something moved, did the client make a mistake, or did the server fail?
Status codes are grouped into five classes by their first digit. The classes are defined in RFC 9110 (HTTP Semantics), the current authoritative specification for HTTP.
The five classes
Informational
The request was received and processing is continuing. Rarely seen in practice outside of WebSocket upgrades.
Success
The request was successfully received, understood, and accepted. The most common class in everyday API use.
Redirection
Further action is needed from the client to complete the request. Always include a Location header pointing to the new URL.
Client errors
The client sent a request the server cannot or will not fulfill. The error is on the caller's side. Always include a body explaining what went wrong.
Server errors
The server encountered an error it could not recover from. The fault is on the server side. Clients may retry 503 and 504; they should not retry 500 or 501.
Choosing the right code for your REST API
The most common source of confusion is not knowing which code to return for a given scenario. Here is a quick-reference for the cases that come up most often:
| Scenario | Code to return |
|---|---|
| GET /users/123: user found | 200 OK |
| POST /users: user created | 201 Created |
| DELETE /users/123: deleted | 204 No Content |
| POST /users: validation failed | 422 Unprocessable Entity |
| GET /users/999: not found | 404 Not Found |
| POST /login: wrong password | 401 Unauthorized |
| GET /admin: not an admin | 403 Forbidden |
| POST /upload: file too large | 413 Content Too Large |
| GET /api: rate limit hit | 429 Too Many Requests |
| GET /users: database down | 503 Service Unavailable |
Frequently asked questions
What is the difference between 401 and 403?
401 means "I do not know who you are." The client has not authenticated or the token is invalid. 403 means "I know who you are, but you are not allowed here." The client is authenticated but lacks the required permission. A common mistake is returning 401 when you mean 403.
When should I use 400 vs 422?
400 Bad Request is for syntactically broken requests: unparseable JSON, a missing Content-Type header, or a required field that is absent. 422 Unprocessable Entity is for requests that parse correctly but fail business logic: a valid email format that is already registered, or a date that is in the past. Many teams use 400 for both, which is acceptable.
What is the difference between 301 and 308?
Both are permanent redirects, but 301 allows browsers to change POST to GET on the redirected request (which they almost always do). 308 requires the method to stay the same. For REST APIs, 308 is the correct choice when permanently redirecting a POST endpoint.
What is the difference between 302 and 307?
Both are temporary redirects, but 302 allows the method to change (browsers typically convert POST to GET). 307 requires the original method to be preserved. Use 307 when you need a temporary redirect and the client might be sending a POST or PUT.
Should I return 404 or 403 for a resource the user cannot access?
It depends on whether you want to reveal that the resource exists. Returning 403 tells the client "this resource exists but you cannot see it." Returning 404 hides that fact entirely. For sensitive resources (admin endpoints, other users' data), 404 is often the safer choice.
What does 418 mean?
418 I'm a Teapot is defined in RFC 2324, an April Fools' joke from 1998 about a Hyper Text Coffee Pot Control Protocol. A server returns 418 when asked to brew coffee using a teapot. It is not intended for production use but has been preserved in HTTP specifications as a piece of internet history.