All HTTP status codes — 1xx to 5xx — with descriptions and use cases.
HTTP Status Reference Guide is a comprehensive quick-reference card for HTTP response status codes. Each code is shown with its standard name, a one-line description, and practical guidance for API developers. Use it to choose the right status code for your REST API responses and to understand what codes mean when debugging HTTP requests.
The HTTP status code system is defined in RFC 9110 (2022, successor to RFC 7231). Codes are grouped: 100-199 (informational), 200-299 (successful), 300-399 (redirection), 400-499 (client errors), 500-599 (server errors). Each code has a reason phrase (e.g., 404 Not Found) that is informational only -- clients should use the numeric code for logic, not the phrase.
Well-designed REST APIs use status codes consistently and correctly: they convey the operation outcome without requiring the client to parse the response body. A client that understands HTTP status codes can handle success, redirects, validation errors, authentication failures, and server errors generically -- only needing to parse body for application-specific details on success or 4xx validation errors.
200 OK
Result: Standard success response for GET, PUT, PATCH -> return the resource in the body
404 Not Found
Result: Resource not found or does not exist -> return JSON error body with details
500 Internal Server Error
Result: Unexpected server error -> log error server-side, return generic message to client
What are the most important HTTP status codes to know?
Essential status codes: 200 OK (standard success), 201 Created (POST success with new resource), 204 No Content (success with no body -- DELETE), 400 Bad Request (malformed request), 401 Unauthorized (authentication required), 403 Forbidden (authenticated but no permission), 404 Not Found (resource does not exist), 409 Conflict (state conflict -- duplicate, concurrent modification), 422 Unprocessable Entity (validation failure), 429 Too Many Requests (rate limited), 500 Internal Server Error (unexpected server failure), 503 Service Unavailable (server temporarily down).
How should REST APIs handle errors?
Best practices: use the correct HTTP status code (4xx for client errors, 5xx for server errors). Include a JSON error body with: error code (machine-readable string like USER_NOT_FOUND), message (human-readable), and optionally errors array (field-level validation errors). Example: {error: 'VALIDATION_ERROR', message: 'Email is invalid', errors: [{field: 'email', message: 'Must be a valid email address'}]}. Never return 200 for errors (common mistake in older APIs). Use 422 for semantic validation errors, 400 for structural/format errors.
What is the difference between 500, 502, 503, and 504?
500 Internal Server Error: unexpected error in your application code -- unhandled exception, bug. Log the full error server-side. 502 Bad Gateway: the server acting as a gateway received an invalid response from an upstream server. Common cause: your load balancer or reverse proxy (Nginx, Cloudflare) cannot reach your backend application. 503 Service Unavailable: server is temporarily unable to handle requests -- maintenance, overload. Include Retry-After header. 504 Gateway Timeout: the gateway did not receive a timely response from the upstream server -- the upstream is too slow. Check for slow database queries or external API calls.
What are 1xx informational status codes used for?
1xx codes are rarely seen by application developers: 100 Continue: server received request headers and client should send the body. Used when client sends Expect: 100-continue header to check if server accepts large uploads. 101 Switching Protocols: server agrees to upgrade (from HTTP to WebSocket via the Upgrade header). 103 Early Hints (2017): server sends preliminary response headers before the full response -- used by CDNs to send Link preload headers for critical resources while generating the main response. 102 Processing (WebDAV): server received the request and is still processing.
What is a 304 Not Modified and how does caching work with it?
304 Not Modified is returned when the client has a cached version that is still valid. The cache validation flow: (1) Server sends ETag: abc123 or Last-Modified: date header with the response. (2) Client caches the response. (3) On next request, client sends If-None-Match: abc123 or If-Modified-Since: date. (4) Server checks if the content changed -- if not, returns 304 with no body. (5) Client uses its cached copy. This saves bandwidth -- the server confirms the cache is fresh without re-sending the content. CDNs use ETags and Last-Modified heavily for efficient caching.