Complete Reference Guide to HTTP Status Codes (RFC 9110)
HTTP Status Codes are 3-digit standardized integer responses established by the Internet Engineering Task Force (IETF) in RFC 9110 and maintained in the official registry of the Internet Assigned Numbers Authority (IANA). Whenever a client (web browser, mobile application, or backend microservice) issues an HTTP request, the receiving server answers with an HTTP response containing a status code communicating the outcome.
1. The Five Canonical Response Classes
- 1xx (Informational): The request was received and the protocol negotiation continues (e.g.,
101 Switching Protocolsduring WebSocket upgrades). - 2xx (Successful): The client's action was successfully understood, accepted, and processed (e.g.,
200 OK,201 Createdon resource creation,204 No Contenton deletions). - 3xx (Redirection): Additional action must be taken to complete the request (e.g.,
301 Moved Permanently,304 Not Modifiedfor cache hits,308 Permanent Redirectpreserving HTTP methods). - 4xx (Client Error): The request contains erroneous syntax, bad parameters, missing authentication, or points to an absent resource (e.g.,
400 Bad Request,401 Unauthorized,403 Forbidden,404 Not Found,429 Too Many Requests). - 5xx (Server Error): The server encountered an unexpected runtime failure while attempting to fulfill a legitimate request (e.g.,
500 Internal Server Error,502 Bad Gateway,503 Service Unavailable).
2. Critical Nuances in REST API Design
Common semantic ambiguities that every backend engineer should understand:
- 401 Unauthorized vs. 403 Forbidden: Code
401indicates missing or invalid authentication ("I don't know who you are; please provide valid credentials"). Code403indicates that authentication succeeded, but the user does not possess administrative or scope-level permissions to read or write the entity ("I know who you are, but you are not permitted here"). - 400 Bad Request vs. 422 Unprocessable Entity: Code
400means the raw request envelope cannot be deserialized (e.g., malformed JSON syntax). Code422indicates syntactically pristine JSON whose payload fails business validation schemas (e.g., negative quantity, invalid date format). - 301 Moved Permanently vs. 308 Permanent Redirect: Legacy
301allows clients to inappropriately rewrite POST requests to GET upon redirecting. Modern RFC 7538 specifies308 Permanent Redirectto strictly guarantee that the HTTP request verb and body remain intact.
Frequently Asked Questions (FAQ)
What causes a 502 Bad Gateway error?+
A 502 Bad Gateway occurs when an edge reverse proxy (such as Nginx, Cloudflare, AWS ALB, or Envoy) attempts to forward an incoming request to an upstream application server (e.g., Node.js, Python FastAPI, Go), but the upstream server crashes, times out, or closes the TCP socket abruptly.
When should an API return 204 No Content?+
Use HTTP 204 No Content when an action succeeds and no response payload needs to be returned to the client. This is common for DELETE operations, PUT updates where returning the entity is unnecessary, or pre-flight CORS OPTIONS queries.
What is HTTP status 429 Too Many Requests?+
HTTP 429 is part of RFC 6585, signaling that the client has exceeded rate limits within a given time window. Servers typically return a 'Retry-After' header indicating the number of seconds the client must wait before making subsequent requests.