HTTP Status Codes Reference

1xx (Informational): provisional responses during request processing (100 Continue, 101 Switching Protocols) - rarely seen by users. 2xx (Success): request succeeded (200 OK, 201 Created, 204 No Content) - everything worked as expected. 3xx (Redirection): further action required (301 Moved Permanently, 302 Found, 304 Not Modified) - resource moved or cached. 4xx (Client Error): client made invalid request (400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found) - problem is with request. 5xx (Server Error): server failed to process valid request (500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable) - problem is with server. Rule: 4xx = client's fault, 5xx = server's fault.

301 Moved Permanently: resource permanently moved to new URL, browsers/search engines should update bookmarks and links, SEO link juice transfers to new URL, aggressive caching (browsers may cache redirect forever), use for permanent URL changes. 302 Found (temporary redirect): resource temporarily at different URL, original URL still valid, search engines keep indexing original URL (no SEO transfer), less aggressive caching, use for maintenance redirects or A/B testing. Wrong choice consequences: 302 for permanent moves hurts SEO (split rankings), 301 for temporary moves makes temporary URL permanent in caches. Modern: 307 (Temporary) and 308 (Permanent) are stricter versions that preserve HTTP method. Always use 301 for permanent URL migrations.

401 Unauthorized: user not authenticated (not logged in), request lacks valid credentials, response includes WWW-Authenticate header prompting login, use when authentication required but missing. 403 Forbidden: user authenticated but lacks permission to access resource, credentials provided but insufficient privileges, use when logged-in user tries accessing forbidden resource (admin panel for regular users). 404 Not Found: resource does not exist at URL, URL is invalid or resource deleted, use when URL never existed or no longer exists. Confusion: 401 should be "Unauthenticated", 403 is true "Unauthorized" but names are historical. Security: return 404 for forbidden resources to hide their existence (unauthorized users should not know resource exists).

200 OK: general success for GET, PUT, PATCH (request succeeded, response body contains resource). Use for most successful operations that return data. 201 Created: resource successfully created (POST request), response includes Location header with new resource URL, response body typically contains created resource representation. Use specifically for creation operations. 204 No Content: successful request but no content to return (DELETE request, PUT update with no response needed), saves bandwidth by not sending body. Use when operation succeeds but client does not need response data. REST conventions: POST creating resource = 201, DELETE removing resource = 204, GET retrieving resource = 200, PUT updating resource = 200 or 204. Proper codes help API clients understand operation results without parsing response body.

502 Bad Gateway: gateway/proxy server (nginx, load balancer) received invalid response from upstream server (backend). Causes: upstream server crashed/restarted, network connectivity issue between proxy and backend, timeout waiting for upstream, upstream returned invalid HTTP. Fix: check upstream server logs, verify backend is running, increase proxy timeout settings, verify network connectivity. 503 Service Unavailable: server temporarily unable to handle request (overloaded, maintenance). Causes: server under heavy load/DDoS, application crashed, max connections reached, intentional maintenance mode. Fix: check server resources (CPU, memory, connections), scale up server capacity, implement rate limiting, check for traffic spikes. User response: both are temporary - retry after delay. APIs should include Retry-After header indicating when to retry.

Best practices: GET retrieval: 200 OK (found), 404 Not Found (missing). POST creation: 201 Created with Location header, 400 Bad Request (validation failed), 409 Conflict (duplicate). PUT update: 200 OK or 204 No Content, 404 Not Found (resource missing). DELETE: 204 No Content (deleted), 404 Not Found (already gone/never existed). Authentication: 401 (not logged in), 403 (insufficient permissions). Validation errors: 400 Bad Request with error details in body. Server errors: 500 Internal Server Error (catch-all). Rate limiting: 429 Too Many Requests. Be consistent: document your codes, return same codes for same situations, include error details in response body, use standard codes (avoid custom codes in 4xx/5xx ranges). Proper codes enable generic client error handling.