HTTP Status Codes
1xx, 2xx, 3xx, 4xx, 5xx — what every number means
Skills taught: web.status-codes, web.error-handling-basics
Status code categories
Every HTTP response starts with a 3-digit status code. The first digit tells you the category — whether the request succeeded, needs to go somewhere else, or failed.
1xx Informational → Request received, keep going (rare)
2xx Success → Request completed successfully
3xx Redirection → Go somewhere else
4xx Client Error → You made a mistake
5xx Server Error → The server is broken
The most important codes
─── 2xx SUCCESS ─────────────────────────────────────────────
200 OK Standard success. Response has a body.
201 Created Resource was created. Body = the new resource.
204 No Content Success, but no body (common for DELETE).
─── 3xx REDIRECT ─────────────────────────────────────────────
301 Moved Permanently Resource permanently moved to Location header.
Browser caches this forever.
302 Found Temporary redirect. Not cached.
304 Not Modified Your cached version is still current — use it.
─── 4xx CLIENT ERROR ──────────────────────────────────────────
400 Bad Request Malformed request (bad JSON, missing field).
401 Unauthorized Not authenticated — you need to log in.
403 Forbidden Authenticated but not allowed.
404 Not Found Resource does not exist.
405 Method Not Allowed This URL does not accept this HTTP method.
409 Conflict State conflict (e.g. duplicate record).
422 Unprocessable Syntactically valid but semantically wrong
(validation failed).
429 Too Many Requests Rate limited. Check Retry-After header.
─── 5xx SERVER ERROR ──────────────────────────────────────────
500 Internal Error Something crashed on the server.
502 Bad Gateway Upstream server returned a bad response.
503 Unavailable Server is down or overloaded (retry later).
504 Gateway Timeout Upstream server took too long.
Tip: 401 vs 403: 401 means 'who are you?' — include credentials and try again. 403 means 'I know who you are, but you are not allowed here' — sending credentials again will not help.
Frequently Asked Questions
Why do some APIs always return 200 even for errors?
Some APIs put error information in the response body and always return 200. This is an anti-pattern — it breaks HTTP semantics and makes it impossible for middleware, caches, and monitoring tools to detect errors automatically. Use proper status codes; the HTTP spec exists precisely to communicate success and failure consistently.
What is the difference between 401 and 403?
401 Unauthorized (confusingly named) means unauthenticated — 'I don't know who you are, please identify yourself'. You should include credentials and try again. 403 Forbidden means authenticated but unauthorized — 'I know who you are, but you're not allowed here'. No amount of credential-providing will fix a 403; you need a permission change.