Common HTTP Status Codes Every Developer Should Know
3 min read · Published
Table of contents
Every HTTP response starts with a three-digit status code that tells the client what happened. Choosing the right one makes APIs easier to consume, debug and cache. Here are the codes you will use daily, grouped by class. For a searchable list of all of them, use the HTTP Status Code Reference.
The five classes
| Range | Class | Meaning |
|---|---|---|
| 1xx | Informational | Request received, continue |
| 2xx | Success | Request succeeded |
| 3xx | Redirection | Further action needed |
| 4xx | Client error | The request is wrong |
| 5xx | Server error | The server failed |
2xx: success
- 200 OK is the default for a successful GET, or an update that returns the resource.
- 201 Created is returned after a POST creates something. Add a
Locationheader pointing to the new resource. - 202 Accepted means "queued, not finished". Use it for background jobs and give clients a URL to poll.
- 204 No Content is success with no body. It is typical for DELETE.
POST /users HTTP/1.1
Content-Type: application/json
{"name":"Ada"}
HTTP/1.1 201 Created
Location: /users/42
3xx: redirection
- 301 Moved Permanently is a permanent move. Browsers and search engines cache it and transfer SEO value.
- 302 Found is a temporary redirect.
- 304 Not Modified tells a client its cached copy is still valid (used with
ETagandIf-None-Match). - 307 / 308 are the temporary and permanent redirects that preserve the method. A POST stays a POST, unlike 301 and 302 where clients may switch to GET.
4xx: the client made a mistake
- 400 Bad Request: malformed syntax, unparsable JSON, missing required parameters.
- 401 Unauthorized: no valid credentials. Despite the name, it means unauthenticated. Send a
WWW-Authenticateheader. - 403 Forbidden: the server knows who you are and you are not allowed. Logging in again will not help.
- 404 Not Found: the resource does not exist, or you prefer not to reveal it exists.
- 405 Method Not Allowed: the path exists but not for this method. Include an
Allowheader. - 409 Conflict: the request conflicts with current state, such as a duplicate username or an edit based on a stale version.
- 410 Gone: permanently removed, a stronger signal than 404 for crawlers.
- 422 Unprocessable Content: the syntax is fine but validation failed, for example an invalid email address.
- 429 Too Many Requests: rate limit hit. Include
Retry-After.
401 versus 403
| Situation | Code |
|---|---|
| No token or an invalid token | 401 |
| Valid token, but a regular user calls an admin endpoint | 403 |
5xx: the server failed
- 500 Internal Server Error: an unexpected bug. Log details on the server; never return stack traces to clients.
- 502 Bad Gateway: a reverse proxy received an invalid reply from the upstream app. Common when the app has crashed.
- 503 Service Unavailable: temporarily overloaded or in maintenance. Add
Retry-After. - 504 Gateway Timeout: the upstream took too long.
Designing an error response
Pair the status code with a machine-readable body so clients can react:
{
"error": {
"code": "validation_failed",
"message": "email must be a valid address",
"fields": { "email": "invalid" }
}
}
Format and inspect responses like this with the JSON Formatter.
Common mistakes
- Returning 200 with an error body. Clients, proxies and monitoring tools all rely on the status code.
- Using 404 for validation errors or 500 for bad input.
- Using 401 when you mean 403, which makes clients loop on re-login.
- Forgetting cache headers on 301 redirects that you later need to change.
Debugging checklist
- Copy the failing request URL; decode it with the URL Decoder if it is encoded.
- Check the code class: 4xx means fix the request, 5xx means check server logs.
- For 401, decode the JWT and check
exp. - For 502 or 504, check whether the upstream service is running.
See also REST API Basics for how status codes fit into API design.
Related tools
HTTP Status Code Reference
Searchable reference of HTTP status codes with explanations.
JSON Formatter
Format, beautify and minify JSON with custom indentation.
URL Encoder
Percent-encode text for safe use in URLs.
FAQ
What is the difference between 401 and 403?
401 means the request lacks valid authentication; 403 means the server knows who you are and you are not allowed.
Should validation errors be 400 or 422?
Both are used. 400 for malformed requests, 422 when the syntax is fine but the data fails validation. Pick one convention and document it.
What does 5xx tell the client?
That the failure is on the server side and the same request may succeed later.
Keep reading
- REST API Basics
Understand REST APIs: resources, HTTP methods, status codes, JSON payloads, idempotency, pagination, versioning and authentication basics.
- How to Format JSON Online (and Fix Common Errors)
Step-by-step guide to formatting, beautifying and minifying JSON online, plus how to read and fix the most common JSON syntax errors.