HTTP status codes: the common ones and what to do

Every HTTP response starts with a three-digit status code. The first digit tells you the category, so even an unfamiliar code gives you a hint: 2xx success, 3xx redirection, 4xx client error (fix the request), 5xx server error (fix or wait for the server).

2xx: it worked

• 200 OK: success, the body has the result.
• 201 Created: a new resource was made. Look for a Location header pointing to it.
• 204 No Content: success with an empty body, common for DELETE and CORS preflight responses.

3xx: look somewhere else

• 301 Moved Permanently and 308 Permanent Redirect: update your links. 308 guarantees the method and body are kept; with 301 clients may switch POST to GET.
• 302 Found and 307 Temporary Redirect: temporary move. 307 keeps the method, 302 may not.
• 304 Not Modified: your cached copy is still valid. Not an error.

curl does not follow redirects unless you add -L. Browsers and fetch() follow them automatically.

4xx: something is wrong with the request

• 400 Bad Request: malformed input, often invalid JSON or a missing field. Read the response body; good APIs explain what failed.
• 401 Unauthorized: you are not authenticated. The token or key is missing, expired, or wrong. Check the Authorization header.
• 403 Forbidden: you are authenticated but not allowed. Check permissions, scopes, or roles; logging in again will not help.
• 404 Not Found: wrong URL, wrong ID, or a resource the server prefers to hide from you.
• 405 Method Not Allowed: the path exists but not for this method, for example POST to a read-only endpoint.
• 409 Conflict: the request clashes with the current state, such as a duplicate username.
• 413 Content Too Large (older name: Request Entity Too Large): the body is bigger than the server accepts.
• 415 Unsupported Media Type: wrong or missing Content-Type.
• 422 Unprocessable Content: the syntax is fine but the data fails validation.
• 429 Too Many Requests: you hit a rate limit. Slow down and honor the Retry-After header if present.

5xx: the server failed

• 500 Internal Server Error: an unhandled error in the application. Check server logs; retrying rarely helps.
• 502 Bad Gateway: a proxy or load balancer got an invalid answer from the app behind it. Is the app running and listening on the expected port?
• 503 Service Unavailable: overloaded or in maintenance. Retry later, ideally with backoff.
• 504 Gateway Timeout: the app behind the proxy took too long. Look for slow queries or raise the proxy timeout carefully.

Checking a status code quickly

# Print only the status code
curl -s -o /dev/null -w '%{http_code}\n' https://example.com/

# Show the status line and headers, then the body
curl -i https://example.com/

In JavaScript, fetch() does not reject on 4xx or 5xx. It only rejects on network failures, so check response.ok (true for 200-299) or response.status yourself.

const response = await fetch("/api/items");
if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}
const items = await response.json();

When you build an API, pick the most specific code that fits and include a short JSON error message in the body. Clients and humans debugging them will both thank you. The full list lives in MDN’s status code reference and in RFC 9110.