HTTP Status Code Lookup

About HTTP Status Code Lookup

How to use the HTTP Status Code Lookup

1. Enter a status code, or search by name or by what happened.
2. Read the meaning, the class it belongs to, and whether it is safe for a client to retry.
3. Check the headers the code expects - WWW-Authenticate with 401, Location with 3xx, Retry-After with 503 and 429, Allow with 405.
4. If you are choosing a code to return, get the class right first; the specific code within it matters less.

Examples

• Not Found

  404

  Copy example
• Internal Server Error

  500

  Copy example

HTTP Status Code Lookup in code

The same operation this tool performs, in the languages you are most likely to need it.

// Authentication vs authorisation
if (!token)            return res.status(401)
  .set("WWW-Authenticate", 'Bearer realm="api"').json({ error: "unauthenticated" });
if (!user.canEdit(doc)) return res.status(403).json({ error: "forbidden" });

// Validation: 400 for unparseable, 422 for parsed-but-invalid
if (!isJson(body))      return res.status(400).json({ error: "malformed JSON" });
if (!schema.valid(body)) return res.status(422).json({ error: schema.errors });

// Rate limiting - always say when to come back
if (overLimit) return res.status(429).set("Retry-After", "60").end();

// Created: include where the new thing lives
res.status(201).set("Location", `/orders/${order.id}`).json(order);

// No body to send
res.status(204).end();          // must NOT have a body

// Which failures are worth retrying, and which are not
function isRetryable(status) {
  if (status === 408 || status === 429) return true;   // timeout, rate limit
  if (status === 425) return true;                     // too early
  if (status >= 500 && status !== 501) return true;    // server-side
  return false;   // other 4xx are your fault - retrying changes nothing
}

async function withRetry(fn, attempts = 4) {
  for (let i = 0; ; i++) {
    const res = await fn();
    if (res.ok || !isRetryable(res.status) || i === attempts - 1) return res;
    // Honour Retry-After when the server sent it
    const after = Number(res.headers.get("Retry-After"));
    const wait = Number.isFinite(after) && after > 0
      ? after * 1000
      : Math.min(2 ** i * 250 + Math.random() * 250, 10_000);
    await new Promise((r) => setTimeout(r, wait));
  }
}

# Status line only
curl -s -o /dev/null -w '%{http_code}\n' https://example.com

# Follow redirects and show each hop
curl -sIL https://example.com | grep -E '^(HTTP|location)'

# See whether a redirect preserves the method (301/302 may not)
curl -sIL -X POST https://example.com/old

# Full headers without a body
curl -sI https://example.com

When you need this

• Deciding which status code your API should return for a given failure.
• Working out whether a client should retry a request it just received.
• Diagnosing why a redirected POST arrived as a GET with no body.
• Explaining the 401/403 distinction during a code review.
• Checking which headers a code requires before you ship it.

Common problems and what causes them

Using 401 when you mean 403

401 means unauthenticated and obliges the server to send WWW-Authenticate; clients respond by trying to authenticate or refresh a token. 403 means authenticated but not permitted. Returning 401 for a permissions failure sends clients into a pointless refresh loop.

A redirected POST becoming a GET

301 and 302 historically permit clients to change the method to GET, and most do. The body is lost. Use 308 for a permanent redirect and 307 for a temporary one when the request may not be a GET.

Returning 200 with an error in the body

A 200 carrying {"error": "not found"} defeats every layer that reasons about status codes - caches, retry logic, monitoring, alerting. Use the status code as the machine-readable signal and the body for detail.

Sending a body with 204 or 304

Neither may carry a body, and doing so causes real problems: some clients and proxies mis-frame the response or hang waiting for content that never arrives.

429 or 503 without Retry-After

Without it, well-behaved clients guess - usually too aggressively, which makes an overload worse. Always send Retry-After with both.

Collapsing every server failure into 500

500 (your code threw), 502 (upstream sent garbage), 503 (deliberately refusing), and 504 (upstream too slow) point at completely different problems. Using one for all four removes the most useful signal you have during an incident.

405 without an Allow header

405 Method Not Allowed is required to list the methods that are allowed. Omitting it leaves the client with no way to correct the request.

FAQ

What is the difference between 401 and 403?

401 Unauthorized means unauthenticated - no valid credentials were supplied - and the response must include a WWW-Authenticate header. 403 Forbidden means the server knows who you are and you are not permitted, so retrying with the same credentials will not help.

400 or 422 for a validation error?

400 Bad Request when the request could not be parsed at all - malformed JSON, a missing required parameter. 422 Unprocessable Entity when it parsed fine but failed your business or schema rules. Both are defensible; be consistent, and document which you use.

301 or 308 - which redirect should I use?

308 if the request might not be a GET, because it guarantees the method and body are preserved. 301 is permitted to downgrade a POST to a GET, and most clients do, which silently drops the body. For permanent GET-only redirects, 301 is fine and better supported by old clients.

Which status codes should a client retry?

408, 425, 429 and 5xx other than 501. Retry with exponential backoff and jitter, and honour Retry-After when it is present. Other 4xx codes indicate a problem with the request itself, so retrying it unchanged cannot succeed.

Is it acceptable to return 200 with an error inside?

It breaks a lot of things quietly: HTTP caches, client retry logic, load balancer health checks and monitoring all key off the status code. Some RPC-over-HTTP protocols do it deliberately, but for a REST-style API it is a mistake.

What does 418 mean?

"I'm a teapot", from an April Fools RFC in 1998. It is not a real status code, though it was formally reserved so that it would not be assigned to anything serious. Some services return it for bot detection.

What's the difference between 401 and 403?

401 Unauthorized means authentication is missing or invalid - the client needs to log in. 403 Forbidden means the server understood who you are but you don't have permission for that specific resource.

Is 422 the same as 400?

Both indicate a client-side problem, but 400 Bad Request usually means malformed syntax the server couldn't parse at all, while 422 Unprocessable Entity means the request was well-formed but failed validation rules.

Related reading

• HTTP header parser
• Online cURL client check a real response