HTTP Status Code Reference

1xx responses are provisional — the server has received part of the request and the client should continue. These are rarely seen by developers in everyday work. The most important is 101 Switching Protocols, returned when upgrading an HTTP connection to WebSocket. 103 Early Hints is a newer addition that allows CDNs and servers to push Link headers for resource preloading before the main response is ready, improving page load performance.

2xx responses indicate the request was received, understood, and accepted. 200 OK is the default success response. 201 Created is the correct response when a POST request creates a new resource — it should include a Location header pointing to the new resource's URL. 204 No Content is correct for DELETE requests and silent updates where no body is needed. 206 Partial Content powers video streaming and resumable downloads via the Range request header.

3xx responses tell the client to look elsewhere for the requested resource. The Location header specifies the new URL. 301 and 308 are permanent redirects — search engines transfer PageRank to the new URL. 302 and 307 are temporary. The critical difference between 301/302 and 308/307 is method preservation: 307 and 308 guarantee that the HTTP method (POST, PUT, etc.) is preserved across the redirect, while 301 and 302 historically caused browsers to downgrade POST to GET.

4xx responses indicate the client made an error. The server understood the request but cannot fulfill it as sent. 400 is the general "bad request" catch-all. 401 triggers authentication (the WWW-Authenticate header specifies the scheme). 403 denies access even to authenticated users. 404 is the most famous: resource not found. 409 indicates a conflict, such as trying to create a duplicate unique record. 422 is increasingly favored for validation errors in REST APIs. 429 indicates rate limiting.

5xx responses indicate the server encountered an error while processing an otherwise valid request. 500 is the generic server error — it should never be returned for client input errors. 502 and 504 indicate proxy/gateway issues — common when your load balancer cannot reach the origin server. 503 with a Retry-After header is the correct way to handle planned maintenance. 507 Insufficient Storage is specific to WebDAV when the server runs out of disk space.

Returning HTTP 200 with {"error": "not found"} in the body breaks HTTP semantics, fools monitoring systems, and forces every client to parse the body before knowing success. Use proper 4xx and 5xx codes.

Client input errors are never the server's fault. Returning 500 for a missing required field is incorrect. Use 400 for malformed requests and 422 for validation failures.

An empty list is a valid successful response — return 200 with an empty array, not 404. Reserve 404 for when the resource itself (e.g. the endpoint or a specific ID) does not exist.

Returning 403 tells an attacker the resource exists but they can't access it. For sensitive resources, return 404 to hide existence. This is a deliberate security tradeoff — choose based on your threat model.

Permanent redirects on API endpoints can break clients that don't follow redirects. Prefer updating documentation and making the old endpoint respond with the correct data for a deprecation period.