HTTP status codes are three-digit numbers returned by a server in response to a client's request, communicating whether the request succeeded, failed, or requires further action. Understanding them is essential for building, debugging, and consuming web APIs and websites.
Every HTTP response includes a status code and a short reason phrase, such as '200 OK' or '404 Not Found'. They are defined by the IETF in RFC 9110 and are grouped into five classes based on their first digit. These codes form a universal language between clients (browsers, apps) and servers. Developers rely on them to determine how to handle responses programmatically.
1xx (Informational) indicates the request was received and processing is continuing. 2xx (Success) means the request was successfully received, understood, and accepted — 200 OK and 201 Created are the most common. 3xx (Redirection) tells the client to take additional action, usually following a new URL. 4xx (Client Error) signals a problem with the request itself, while 5xx (Server Error) means the server failed to fulfill a valid request.
200 OK is the standard success response for GET and POST requests. 201 Created is returned when a resource is successfully created, common in REST APIs. 301 Moved Permanently and 302 Found handle URL redirects, with 301 being permanent and cache-friendly. 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, and 429 Too Many Requests are the most frequent client-side errors you will debug.
When a server processes a request, it generates a response that begins with a status line containing the HTTP version, the status code, and the reason phrase (e.g., 'HTTP/1.1 404 Not Found'). The client reads this status line before parsing headers or the response body. Intermediate layers like proxies, CDNs, and load balancers may modify or generate their own status codes. For example, a CDN might return 503 Service Unavailable if the origin server is unreachable.
A common mistake is assuming a 200 response means the operation succeeded at the business logic level. Some APIs embed error details in the response body while still returning 200, which is considered bad practice but exists in the wild. Always validate both the status code and the response payload when consuming third-party APIs. Follow REST conventions: use 4xx for client faults and 5xx for server faults to make your API self-describing.
Return the most specific status code available — use 422 Unprocessable Entity for validation errors rather than the generic 400. Never expose internal server details in 5xx error bodies, as this can leak sensitive information. Use 404 vs 403 carefully: returning 404 for a resource the user is not authorized to see can prevent information leakage about its existence. Always include a machine-readable error body alongside 4xx and 5xx codes to help API consumers debug issues programmatically.
© RM Full Stack & AI Engineer · All guides · Roadmaps · Open the app