1.4.b — HTTP Status Codes for Responses

In one sentence: Every HTTP response begins with a 3-digit status code that tells the client (and caches, CDNs, and developers) whether the request succeeded, needs a redirect, failed because of the client, or failed because of the server.

Navigation: ← 1.4.a — HTTP & Versions · 1.4.c — HTTPS vs HTTP →

---

1. The Status Line

HTTP/1.1 404 Not Found

• 404 is the status code (machine meaningful)
• Not Found is the reason phrase (human hint; clients should not rely on its exact text)

---

2. Families (Memorize the Pattern)

Family	Meaning	Who “messed up” (usually)
1xx	Informational — continue / early hints	neither
2xx	Success	nobody
3xx	Redirection — client should look elsewhere / use cache rules	often nobody (normal navigation)
4xx	Client error — bad request / auth / forbidden / not found	client (or caller)
5xx	Server error — upstream failed / overloaded	server

---

3. The Codes You Should Know Cold

Success

Code	Name	Typical meaning
200	OK	Success with a body
201	Created	Resource created; often includes Location
204	No Content	Success; intentionally no body

Redirection

Code	Name	Typical meaning
301	Moved Permanently	Old URL permanently replaced (SEO: update links)
302	Found	Temporary redirect (historically misused)
304	Not Modified	Conditional GET satisfied — use cached representation

Client errors

Code	Name	Typical meaning
400	Bad Request	Malformed syntax / invalid parameters
401	Unauthorized	Authentication required or failed
403	Forbidden	Authenticated (sometimes) but not allowed
404	Not Found	No resource at URL (or hidden as 404)
405	Method Not Allowed	POST not supported on this route, etc.
409	Conflict	State conflict (duplicate email, version mismatch)
413	Payload Too Large	Body too big
415	Unsupported Media Type	Wrong Content-Type for this endpoint
429	Too Many Requests	Rate limited

Server errors

Code	Name	Typical meaning
500	Internal Server Error	Unhandled exception / bug
502	Bad Gateway	Proxy/gateway got invalid response from upstream
503	Service Unavailable	Overload / maintenance
504	Gateway Timeout	Upstream too slow

---

4. The Famous Interview Trap: 401 vs 403

RFC-strict story:

• 401 Unauthorized — “Who are you?” Missing/invalid authentication. A WWW-Authenticate header is appropriate in many cases.
• 403 Forbidden — “I know who you are (or I don’t care), but you can’t do this.”

Reality: some APIs return 403 for “not logged in.” Strong candidates explain both the RFC intent and real-world inconsistency.

---

5. Caching-Relevant Codes (Brief)

• 304 Not Modified is not “an error” — it’s a bandwidth win when validators (ETag, If-None-Match) match.
• 301 vs 302 matters for caches and SEO — permanent vs temporary moves have different caching implications.

---

6. Designing Good APIs (Practical Rules)

1. Use the right family — don’t return 200 with {"error": true} for real failures (common anti-pattern).
2. Be consistent — pick conventions for auth errors and stick to them across endpoints.
3. Add details carefully — error bodies help developers; avoid leaking secrets or internal stack traces in production.
4. Rate limits — prefer 429 with Retry-After when possible.

---

7. Key Takeaways

1. Status codes are grouped by the first digit (1xx–5xx).
2. Learn 200/201/204, 301/302/304, 400/401/403/404/429, 500/502/503/504 first.
3. 401 vs 403 tests whether you understand authentication vs authorization.
4. Treat the reason phrase as decorative — rely on the numeric code.

---

Explain-It Challenge

1. When would you return 201 instead of 200?
2. What does 502 imply about your architecture if you’re behind Nginx?
3. Why is 304 considered a success even though no document body is returned?

---

Navigation: ← 1.4.a — HTTP & Versions · 1.4.c — HTTPS vs HTTP →