HTTP Status Codes Reference

HTTP status codes are three-digit numbers returned by web servers in response to client requests. They indicate whether a request succeeded (2xx), was redirected (3xx), failed due to a client error (4xx), or failed due to a server error (5xx). The first digit defines the category, and the remaining digits identify the specific condition.

401 Unauthorized means the request lacks valid authentication credentials — the user needs to log in or provide a valid API key. 403 Forbidden means the server understood the request and the user is authenticated, but they do not have permission to access the resource. Authentication will not help with a 403.

Return 404 Not Found when a resource does not exist or its existence is uncertain. Return 410 Gone when you know the resource existed previously but has been intentionally and permanently removed. 410 tells search engines to de-index the URL, while 404 leaves the possibility of return.

HTTP 429 Too Many Requests means the client has exceeded the rate limit imposed by the server. The response typically includes a Retry-After header indicating how long to wait before retrying. Implement exponential backoff in your client code to handle this gracefully.

Both indicate permanent redirects, but 301 allows the browser to change the HTTP method (e.g., POST to GET), while 308 preserves the original HTTP method. Use 301 for standard URL changes (HTTP to HTTPS, domain migration). Use 308 when you need to ensure POST requests remain POST after the redirect.

This reference includes all standard HTTP status codes from RFC 9110 (HTTP Semantics, 2022) which consolidated and replaced the older RFC 7231. It also includes extension codes from WebDAV (RFC 4918), rate limiting (RFC 6585), and other commonly used specifications.

201 Created, with a Location header pointing at the URL of the new resource (e.g. Location: /api/orders/9876). Many APIs return a bare 200, but 201 + Location is the RFC-correct answer: it tells the client a resource was created and exactly where to find it, which lets generic HTTP clients and caches behave properly. Include the created object in the body so the client doesn't need a follow-up GET.

Use 400 Bad Request when the request itself is malformed — broken JSON, a missing required field, the wrong content type. Use 422 Unprocessable Content when the syntax is perfectly valid but the data fails business rules — an email that's well-formed but already taken, a start date after an end date, a quantity that exceeds stock. The distinction tells the client whether to fix their request format (400) or fix the values (422), which makes error handling far cleaner.