🌐 HTTP Status Code Reference

Despite the name, 401 Unauthorized actually means 'unauthenticated' — the request lacks valid credentials. The server is saying 'tell me who you are.' The response should include a WWW-Authenticate header indicating how to authenticate. 403 Forbidden means 'I know who you are, but you do not have permission to access this.' Authentication would not help — the resource is forbidden for this user. Common mistake: using 403 when you should use 401. If the user is not logged in, return 401. If they are logged in but lack the required role or permissions, return 403. Returning 404 instead of 403 for private resources is also common — hiding existence is a security choice, not an error classification.

200 OK: the request succeeded and the response body contains the result. Use for GET, PUT, PATCH responses that return the updated resource. 201 Created: a new resource was successfully created. Use for successful POST requests that create new records. The response should include a Location header pointing to the new resource URL. 204 No Content: the request succeeded but there is nothing to return. Use for DELETE requests (resource deleted, nothing to return) and some PUT/PATCH operations where the client does not need the updated resource back. Returning 200 with an empty body is functionally equivalent to 204 but semantically less precise.

301 Moved Permanently: the resource has permanently moved. Browsers cache this — after the first visit, the browser goes directly to the new URL. Search engines transfer link equity and update their index. 302 Found: temporary redirect. Browsers do not cache it — every request hits the original URL first. Search engines keep the original URL indexed. 307 Temporary Redirect: like 302, but explicitly preserves the HTTP method (a POST to a 307-redirected URL is re-POSTed, not converted to GET). 308 Permanent Redirect: like 301, but preserves the method. Use 301 for permanent URL changes and HTTPS upgrades. Use 302 for temporary maintenance pages.

429 means you have exceeded the API's rate limit. The response should include a Retry-After header indicating when you can try again (either a seconds delay or a specific timestamp). Proper handling: implement exponential backoff — wait for Retry-After seconds if provided, or double your wait time on each consecutive 429 (start at 1s, then 2s, 4s, 8s, up to a maximum). Add jitter (random delay) to prevent synchronized retries from multiple clients all hitting the API at the same moment (thundering herd). Track your request rate and stay under the documented limit rather than reacting to 429s.

500 Internal Server Error: the server encountered an unexpected error — a bug, unhandled exception, or misconfiguration in the application code. 502 Bad Gateway: the gateway/proxy received an invalid response from the upstream server — typically means the upstream server is down or returning garbage. 503 Service Unavailable: the server is temporarily unable to handle the request — usually during maintenance, overload, or startup. Should include Retry-After. 504 Gateway Timeout: the gateway/proxy did not receive a timely response from upstream — the upstream server is too slow or unresponsive. 502 and 504 appear at the load balancer/CDN level when backend services fail.

418 is an April Fools' joke from RFC 2324 (1998) — the Hyper Text Coffee Pot Control Protocol. The spec defines 418 as the response when a teapot is asked to brew coffee. It was never a serious HTTP status code and was not supposed to be implemented. It survived as an Easter egg and is used by some APIs for humorous responses. Despite being a joke, 418 is listed in the IANA HTTP Status Code Registry (marked as unused) and Node.js, Go, and Python all include it in their HTTP status code constants. It occasionally appears in API error responses for 'this request makes no sense' situations, where the developer wanted to signal an absurd request without implying a real error.

The HTTP Headers Analyzer decodes response headers including the status code context. The curl Builder generates commands that reveal status codes when testing endpoints. The API Response Time Calculator models timeout values relative to expected response times. The JWT Decoder inspects auth tokens that affect which status code an API returns (valid token vs expired = 200 vs 401). The Meta Tag Generator includes HTTP-equiv tags that can influence browser behavior for certain status codes. All are in the Dev Tools section.