HTTP Status Codes Explained: A Developer's Cheat Sheet for 1xx to 5xx

Every HTTP response carries a three-digit status code, and choosing the right one is part of designing a good API. Return 200 for an error and clients silently break; return 500 for a bad request and you page an on-call engineer for nothing. This guide walks through what each class of code means and highlights the ones worth memorizing.

How status codes are organized

The first digit defines the class of response, which gives you an instant read on what happened even for codes you have never seen:

• 1xx — Informational. The request was received and processing continues (e.g. 101 Switching Protocols during a WebSocket upgrade).
• 2xx — Success. The request succeeded (200 OK, 201 Created, 204 No Content).
• 3xx — Redirection. Further action is needed, usually following a new URL (301, 302, 304 Not Modified).
• 4xx — Client error. The request was malformed or not allowed (400, 401, 403, 404, 429).
• 5xx — Server error. The server failed to fulfill a valid request (500, 502, 503).

The codes you will actually use

For a typical REST API, a small vocabulary covers almost everything:

• 200 OK — standard success with a body.
• 201 Created — a resource was created; include a Location header.
• 204 No Content — success with nothing to return (e.g. a DELETE).
• 400 Bad Request — the client sent invalid data.
• 401 Unauthorized — authentication is missing or invalid.
• 403 Forbidden — authenticated, but not allowed.
• 404 Not Found — the resource does not exist.
• 409 Conflict — the request conflicts with current state.
• 422 Unprocessable Entity — well-formed but semantically invalid.
• 429 Too Many Requests — rate limited; pair with Retry-After.
• 500 Internal Server Error — an unhandled exception on your side.

401 versus 403: the classic mix-up

These two trip people up constantly. 401 means I do not know who you are — the credentials are missing or invalid, so re-authenticating might help. 403 means I know exactly who you are, and you still cannot do this — no amount of re-authenticating will change the answer.

A practical walkthrough: handling codes in fetch

Note that fetch only rejects on network failure, not on 4xx/5xx responses — you must inspect response.status yourself:

async function getUser(id) {
  const res = await fetch(`/api/users/${id}`);

  if (res.status === 404) {
    return null; // resource genuinely absent
  }
  if (res.status === 429) {
    const wait = res.headers.get('Retry-After');
    throw new Error(`Rate limited, retry after ${wait}s`);
  }
  if (!res.ok) { // covers any other 4xx/5xx
    throw new Error(`Request failed: ${res.status}`);
  }
  return res.json();
}

The res.ok shortcut is true only for 2xx codes — a clean way to branch between success and everything else.

Common pitfalls

• Do not return 200 with an error payload. Clients, proxies and monitoring tools all key off the status code; hiding failures behind 200 defeats them.
• 301 versus 302 matters for SEO. 301 is permanent and cached aggressively; 302 is temporary. Choose deliberately.
• Reserve 5xx for real server faults. A user sending bad input is a 4xx, not a 500 — otherwise your error dashboards cry wolf.
• Include a machine-readable body with 4xx responses so clients can react programmatically, not just display a string.

Conclusion

Status codes are a shared contract: pick the one that most precisely describes what happened and clients, caches and tooling all cooperate for free. Keep the common two dozen in your head and look up the rest. Browse and search every code in the HTTP Status Codes reference, and when you are debugging responses, the URL Parser and JWT Decoder help you inspect the requests behind them.