Skip to main content

We earn commissions, at no additional cost to you, when you shop through the links below. Learn more

DevBench
webreferencedebugging

HTTP Status Codes Explained: The Codes Developers Actually Use

November 22, 20267 min read

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 a Location header 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 a Range request. 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 nginx client_max_body_size and your platform's cap before blaming app code.
  • 415 Unsupported Media Type — wrong Content-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 a Retry-After header 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

CodeNameWhat it means in practice
200OKStandard success with a body
201CreatedPOST made a new resource; check Location header
204No ContentSuccess, nothing to return
301Moved PermanentlyURL is gone for good; SEO transfers
304Not ModifiedCache is fresh; no body sent
308Permanent Redirect301 that keeps the request method
400Bad RequestUnparseable request syntax
401UnauthorizedNot logged in (or bad credentials)
403ForbiddenLogged in, but not allowed
404Not FoundNo resource at this URL
409ConflictCollides with current state
422Unprocessable ContentValid JSON, failed validation
429Too Many RequestsRate limited; respect Retry-After
502Bad GatewayUpstream sent an invalid response
503Service UnavailableOverloaded 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

Recommended for developers

These are affiliate links: we earn commissions, at no additional cost to you, when you shop through the links below.