HTTP Status Codes
Every code, searchable, with the cause and the fix.
How to read a status code
The first digit tells you the story: 1xx informational (rarely seen), 2xx success, 3xx redirect, 4xx your request was wrong, 5xx the server broke. When debugging an API integration, the code narrows the problem instantly: a 401 is an auth issue (missing or expired token), a 403 means auth succeeded but you lack permission, a 429 means slow down, and a 502/504 usually points to an infrastructure layer (proxy, upstream) rather than your code.
The two most misused codes: 200 returned with an error body (breaks client retry logic — use 4xx/5xx so frameworks react correctly), and 404 for " forbidden" cases that should be 403 or 401. Choosing accurate codes makes your API behave correctly under interceptors, retries and monitoring.
FAQ
What's the difference between 401 and 403?
401 = "who are you?" (unauthenticated, retry with credentials). 403 = "I know who you are, but no" (unauthorized, retrying won't help).
Should I return 400 or 422 for validation errors?
Both are accepted; 422 signals "syntactically valid, semantically wrong" (WebDAV origin, now common in APIs). If unsure, 400 with an error detail body is safest.