Status codes are the API's body language. Using them wrong confuses every client; reading them right speeds up all debugging.
The families
- 2xx — success: 200 OK · 201 Created (after POST) · 204 No Content (after DELETE)
- 3xx — redirects: 301 moved permanently (SEO juice transfers) · 302 temporary · 304 not modified (cache hit)
- 4xx — YOUR request is wrong: 400 bad input · 401 who are you? (no/invalid auth) · 403 I know you, you're not allowed · 404 not found · 409 conflict · 429 slow down (rate limit)
- 5xx — THE SERVER broke: 500 unhandled crash · 502 bad gateway (upstream died) · 503 overloaded/maintenance
The interview trap: 401 vs 403
401 Unauthenticated — missing/invalid credentials, "please log in". 403 Forbidden — valid login, insufficient permission, "you can't do that". Naming this cleanly is a mini flex.
Debugging heuristic
4xx → check your request (URL, body, headers, token). 5xx → check the server logs. This one habit halves debugging time.