Understanding HTTP Status Codes for Developers
SkillVeris Team
Engineering Team
HTTP status codes are three-digit numbers a server sends to tell the client whether a request succeeded, redirected, failed, or errored.
In this guide, you'll learn:
- The first digit sets the class: 1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error.
- 200 OK, 201 Created, and 204 No Content are the success codes you will return most often.
- 4xx codes blame the client — 400, 401, 403, 404, and 429 each describe a different failure to fix.
- 5xx codes blame the server — 500, 502, and 503 signal problems your backend must handle.
1What Are HTTP Status Codes?
HTTP status codes are three-digit numbers a server returns with every response to tell the client what happened to its request. A 200 means success, a 404 means the resource was not found, and a 500 means the server broke. They are a shared vocabulary that lets any client and any server communicate outcomes without ambiguity.
Every HTTP response carries one, whether you set it deliberately or accept the framework default. Understanding them turns cryptic browser and API errors into precise, actionable information — and choosing the right one makes the APIs you build far easier to consume.
2The Five Classes of Status Codes
The first digit of a status code defines its category, so you can grasp the general meaning even for a code you have never seen. Memorizing the five classes is more valuable than memorizing individual numbers.
- 1xx Informational — the request was received and processing continues.
- 2xx Success — the request was received, understood, and accepted.
- 3xx Redirection — further action is needed to complete the request.
- 4xx Client Error — the request has a problem the client must fix.
- 5xx Server Error — the server failed to fulfill a valid request.
💡Quick Mental Model
2xx is 'here you go', 3xx is 'look elsewhere', 4xx is 'you messed up', and 5xx is 'I messed up'. That framing covers most real-world debugging.
32xx Success Codes
The 2xx family confirms that the request worked. Returning the most specific one gives clients useful detail beyond a bare 200.
- 200 OK — the standard success response for GET and most requests.
- 201 Created — a new resource was created, typically after a POST.
- 202 Accepted — the request was accepted for processing but is not done yet.
- 204 No Content — success with nothing to return, common after a DELETE.
When to Use 201 vs 200
Return 201 specifically when a request creates a resource, and include a Location header pointing to the new item. For reads and in-place updates, 200 is correct. Getting this distinction right makes a REST API feel polished and predictable.
43xx Redirection Codes
The 3xx family tells the client the resource lives somewhere else or has not changed. Browsers follow most redirects automatically, but the distinction between permanent and temporary matters for SEO and caching.
- 301 Moved Permanently — the URL changed for good; search engines update their index.
- 302 Found — a temporary redirect; keep using the original URL.
- 304 Not Modified — the cached copy is still valid, so no body is sent.
- 307 and 308 — like 302 and 301 but guaranteed to preserve the HTTP method.
⚠️301 Is Forever
Browsers and proxies cache 301 responses aggressively. Use 302 for temporary moves — an accidental 301 can be painful to undo because clients keep honoring it.
54xx Client Error Codes
The 4xx family means the client made a mistake the server cannot fix — bad input, missing credentials, or a wrong URL. These are the codes you will design most carefully in an API, because they guide callers toward correcting their request.
- 400 Bad Request — malformed syntax or invalid data in the request.
- 401 Unauthorized — authentication is missing or invalid; log in first.
- 403 Forbidden — authenticated, but not allowed to access this resource.
- 404 Not Found — the resource does not exist at this URL.
- 409 Conflict — the request conflicts with the current state, like a duplicate.
- 429 Too Many Requests — the client hit a rate limit and should slow down.
401 vs 403: A Common Mix-Up
Use 401 when the server does not know who you are — credentials are absent or invalid. Use 403 when it knows exactly who you are but you lack permission. Confusing the two leads clients to retry logins that can never succeed.
65xx Server Error Codes
The 5xx family means the request was valid but the server failed to handle it. These point at bugs, outages, or overload on your side, and they should trigger alerts because users cannot fix them.
- 500 Internal Server Error — a generic, unhandled failure in your code.
- 502 Bad Gateway — an upstream server returned an invalid response.
- 503 Service Unavailable — the server is overloaded or down for maintenance.
- 504 Gateway Timeout — an upstream server did not respond in time.
7Common Mistakes to Avoid
Status codes are easy to get subtly wrong, and the wrong code quietly breaks clients that rely on them.
- Returning 200 with an error message in the body — clients read the code first and think it worked.
- Using 404 for permission problems — leaks less information but confuses debugging; prefer 403 unless hiding existence is intentional.
- Sending 500 for bad user input — that is a 400; reserve 500 for real server faults.
- Ignoring 429 rate limits as a client — always read Retry-After and back off.
- Redirecting with 301 during testing — the permanent cache will haunt you later.
🔑The Golden Rule
Never return a 2xx code for a failed operation. The status line is the first thing every client, proxy, and monitoring tool reads — make it tell the truth.
8Key Takeaways
A working grasp of status codes comes down to a few reliable rules.
- The first digit tells you the class: 2xx success, 3xx redirect, 4xx client error, 5xx server error.
- Return the most specific 2xx code — 201 for creation, 204 for empty success.
- 4xx blames the client; distinguish 401 (who are you?) from 403 (not allowed).
- 5xx blames the server; treat these as bugs and alert on them.
- Never mask a failure behind a 200 — the status code is part of the contract.
9Frequently Asked Questions
Q: What is the difference between 401 and 403? A: 401 Unauthorized means you have not proven who you are — authentication failed or is missing. 403 Forbidden means you are authenticated but lack permission for this resource. Fix a 401 by logging in; a 403 needs different access rights.
Q: When should I use 200 versus 201? A: Use 200 for successful reads and updates. Use 201 specifically when a request creates a new resource, and include a Location header pointing to it. The distinction tells clients that something new now exists.
Q: Is a 404 always an error to fix? A: Not necessarily. A 404 correctly signals that a resource does not exist, which is a valid answer for a client asking about a missing item. It only indicates a bug when a resource that should exist cannot be found.
Q: What does a 429 status code mean? A: 429 Too Many Requests means you exceeded a rate limit. Check the Retry-After header, wait the indicated time, and slow your request rate. Repeatedly ignoring it can get your client blocked entirely.
Related Reading
Get The Print Version
Download a PDF of this article for offline reading.
About the Publisher
SkillVeris Team
Engineering Team
Our engineering writers turn abstract code concepts into hands-on, project-driven learning experiences.
View all postsRelated Posts
Never miss an update
Get the latest tutorials and guides delivered to your inbox.
No spam. Unsubscribe anytime.