HTTP Status Code Reference

HTTP status codes are 3-digit numbers a server returns with every response to indicate the outcome of a request. They're grouped into 5 classes: 1xx (informational), 2xx (success), 3xx (redirection), 4xx (client error), and 5xx (server error). Understanding them is essential for debugging APIs, building error handling, and interpreting server logs.

401 Unauthorized means the server doesn't know who you are — authentication is missing or invalid. 403 Forbidden means the server knows who you are but you don't have permission. Use 401 when credentials are absent or wrong; use 403 when the user is authenticated but lacks access rights.

301 Moved Permanently tells browsers and search engines to permanently update their records — SEO equity passes and the redirect is cached. 302 Found is temporary, so the original URL is preserved and not cached. Use 301 for permanent URL changes and domain migrations; use 302 for login flows, A/B testing, and temporary redirects.

429 indicates rate limiting — the client has exceeded the allowed request rate. Servers should include a Retry-After header showing when to retry. Clients should implement exponential backoff with jitter. This is the standard way to protect APIs from abuse without returning a 503.

400 Bad Request is for syntactically malformed requests (invalid JSON, missing Content-Type header). 422 Unprocessable Entity is for syntactically valid but semantically invalid input (correct JSON structure, but a field fails validation like 'age' being -5). Use 422 for form/field validation errors in modern APIs.

404 Not Found means the resource doesn't exist or you're not revealing its existence. 410 Gone means the resource previously existed but has been permanently deleted — this signals crawlers to deindex the URL and removes it from search results faster. Use 410 when you deliberately retire URLs; 404 is fine when you don't track deletions.

For rate limiting, use 429 with a Retry-After header. For planned maintenance or temporary unavailability, use 503 Service Unavailable, also with a Retry-After header. 503 is the correct code when your server is up but intentionally not serving requests. Avoid using 500 for either scenario.