HTTP Status Codes Explained: The Codes Developers Actually Use
Every API response, every page load, every failed deploy comes down to a three-digit number. HTTP status codes look like trivia until you are debugging a production incident at 2 AM and the difference between a 502 and a 504 tells you which service to restart. This is the working set of codes that actually show up in logs, plus the ones that quietly change how browsers and caches treat your site.
The five classes, in one glance
The first digit is the category. 1xx is informational (rare in practice, mostly protocol upgrades like 101 Switching Protocols for WebSockets). 2xx means success. 3xx means the resource lives somewhere else, or has not changed. 4xx means the client sent something wrong. 5xx means the server failed. If you remember nothing else: 4xx is your caller's fault, 5xx is yours.
2xx — success is not always 200
200 OK covers most responses, but three others carry real meaning:
201 Created— the correct response to a POST that makes a new resource. Return it with aLocationheader pointing at the new resource. Clients that poll for creation depend on this.204 No Content— success with an empty body. Ideal for DELETE endpoints and fire-and-forget updates. Sending a 200 with{}instead forces clients to parse a meaningless payload.206 Partial Content— the server honored aRangerequest. This is what makes resumable downloads and video scrubbing work; if you serve large files, check that your CDN passes it through.
3xx — the redirect codes that change SEO and caching
301 Moved Permanently tells browsers and search engines the old URL is gone forever; Google transfers ranking signals to the target. 302 Found is a temporary move and passes nothing. Sending a 302 when you mean 301 is one of the most common silent SEO bugs — the old URL keeps competing with the new one in search results.
307 and 308 are the strict modern versions: unlike 301/302, they forbid changing the request method, so a POST stays a POST. Use 308 Permanent Redirect for API endpoint migrations where a method flip would break clients.
304 Not Modified is the quiet performance win. When a browser revalidates with If-None-Match or If-Modified-Since and your ETag or timestamp still matches, a 304 sends no body at all. On repeat visits this is the difference between transferring 200 KB and transferring 200 bytes.
4xx — client errors, and the two everyone confuses
401 Unauthorized means "you are not authenticated" — no valid credentials were presented. 403 Forbidden means "I know who you are, and you are not allowed." Returning 403 for a logged-out user sends them in circles; returning 401 when permissions are the problem sends them to re-login for no reason. The names are misleading (401 should have been called Unauthenticated), but the distinction matters for client retry logic.
400 Bad Request— malformed syntax; the request could not be parsed at all.404 Not Found— no resource at this URL. For APIs, also correct when the ID does not exist; do not return 200 with an error body.409 Conflict— the request collides with current state, like creating a username that exists or editing a stale version of a record.413 Payload Too Large— body exceeds the server limit; check nginxclient_max_body_sizeand your platform's cap before blaming app code.415 Unsupported Media Type— wrongContent-Type, usually JSON sent as form data or vice versa.422 Unprocessable Content— syntactically valid JSON that fails validation. Preferred over 400 for field-level errors in modern APIs.429 Too Many Requests— rate limited. Always pair it with aRetry-Afterheader so well-behaved clients back off instead of hammering.
5xx — server errors, and which service to blame
500 Internal Server Error is the generic "code threw an exception." 502 Bad Gateway means a proxy (nginx, a load balancer, Cloudflare) got an invalid response from the upstream — the app server answered badly or crashed mid-response. 503 Service Unavailable means the server is alive but refusing work: overload, maintenance mode, or a deploy in progress; send Retry-After with it. 504 Gateway Timeout means the proxy waited and the upstream never answered — the request is probably still running somewhere.
The practical split: 502 says "the upstream talked nonsense," 504 says "the upstream said nothing." If you see 504s during traffic spikes, look at slow queries and worker pools, not crashes.
Quick reference: the 15 codes worth memorizing
| Code | Name | What it means in practice |
|---|---|---|
200 | OK | Standard success with a body |
201 | Created | POST made a new resource; check Location header |
204 | No Content | Success, nothing to return |
301 | Moved Permanently | URL is gone for good; SEO transfers |
304 | Not Modified | Cache is fresh; no body sent |
308 | Permanent Redirect | 301 that keeps the request method |
400 | Bad Request | Unparseable request syntax |
401 | Unauthorized | Not logged in (or bad credentials) |
403 | Forbidden | Logged in, but not allowed |
404 | Not Found | No resource at this URL |
409 | Conflict | Collides with current state |
422 | Unprocessable Content | Valid JSON, failed validation |
429 | Too Many Requests | Rate limited; respect Retry-After |
502 | Bad Gateway | Upstream sent an invalid response |
503 | Service Unavailable | Overloaded or in maintenance |
A debugging habit that pays off
When an integration fails, read the status code before the error message. The code tells you whose problem it is and whether a retry will help: 4xx means fix the request (retrying unchanged is pointless), 429 means retry later with backoff, 5xx means retry soon but alert if it persists. Half of API debugging is just honoring that split.
Need the full list, searchable, with what triggers each code and when to use it? Our HTTP Status Reference covers every code from 100 to 599, free and in your browser.
Related reading: how JWT authentication works (the source of many 401s), the JSON mistakes behind most 400s, and URL encoding for the 414s and malformed-query 400s.
Try it yourself
Use the free browser-based HTTP Status Reference on DevBench — no signup, runs entirely in your browser.
Open HTTP Status Reference