Understanding HTTP Status Codes in RESTful APIs

In the world of RESTful API development, communication between the client and the server must be clear and standardized. While the request body and headers provide details, the HTTP Status Code is the primary way a server communicates the outcome of a request. Understanding these codes is essential for building robust, self-descriptive, and user-friendly APIs.

What are HTTP Status Codes?

An HTTP status code is a three-digit integer returned by the server to indicate the result of a client's request. These codes are categorized into five distinct ranges, each representing a different type of response. In our previous lesson on HTTP Methods, we discussed how clients send requests; now we focus on how the server replies.

The Five Categories of Status Codes

1xx (Informational): The request was received, and the process is continuing.
2xx (Success): The action was successfully received, understood, and accepted.
3xx (Redirection): Further action needs to be taken to complete the request.
4xx (Client Error): The request contains bad syntax or cannot be fulfilled.
5xx (Server Error): The server failed to fulfill an apparently valid request.

Logic Flow of Status Codes

When a server processes a request, it follows a logical path to determine which status code to return. Below is a simplified representation of this decision-making process:

    [Client Request]
           |
           v
    Is the request valid? ---- No ----> [400 Bad Request]
           | Yes
           v
    Is user authenticated? --- No ----> [401 Unauthorized]
           | Yes
           v
    Does resource exist? ----- No ----> [404 Not Found]
           | Yes
           v
    Did an error occur? ------ Yes ----> [500 Internal Server Error]
           | No
           v
    [200 OK / 201 Created]

Commonly Used Status Codes in REST

2xx Success Codes

200 OK: The standard response for successful HTTP requests. Used for GET, PUT, or DELETE.
201 Created: The request has been fulfilled and has resulted in one or more new resources being created. Commonly used with POST.
204 No Content: The server successfully processed the request but is not returning any content. Often used for successful DELETE operations.

4xx Client Error Codes

400 Bad Request: The server cannot process the request due to client error (e.g., malformed request syntax).
401 Unauthorized: The client must authenticate itself to get the requested response.
403 Forbidden: The client does not have access rights to the content (even if they are logged in).
404 Not Found: The server cannot find the requested resource.
405 Method Not Allowed: The request method is known by the server but is not supported by the target resource.

5xx Server Error Codes

500 Internal Server Error: A generic error message when the server encounters an unexpected condition.
503 Service Unavailable: The server is not ready to handle the request (e.g., down for maintenance or overloaded).

Practical Java Example: Spring Boot Controller

In Java development, specifically using Spring Boot, we can precisely control the status codes returned to the client using the ResponseEntity class.

    @RestController
    @RequestMapping("/api/products")
    public class ProductController {

        @PostMapping
        public ResponseEntity<Product> createProduct(@RequestBody Product product) {
            Product savedProduct = service.save(product);
            // Returning 201 Created instead of a generic 200
            return new ResponseEntity<>(savedProduct, HttpStatus.CREATED);
        }

        @GetMapping("/{id}")
        public ResponseEntity<Product> getProduct(@PathVariable Long id) {
            return service.findById(id)
                .map(product -> new ResponseEntity<>(product, HttpStatus.OK))
                .orElse(new ResponseEntity<>(HttpStatus.NOT_FOUND));
        }
    }

Real-World Use Cases

E-commerce Checkout: When a user submits an order (POST), the server returns 201 Created with the order details. If the credit card is declined, it might return 402 Payment Required (though 400 is more common).
User Login: If a user enters the wrong password, the API should return 401 Unauthorized. If the user tries to access an admin panel without permission, return 403 Forbidden.
API Rate Limiting: If a client sends too many requests in a short time, the server returns 429 Too Many Requests.

Common Mistakes to Avoid

Using 200 OK for Errors: Never return a 200 status code if the response body contains an error message like "{ "error": "not found" }". Use 404 instead.
Confusing 401 and 403: 401 means "I don't know who you are," while 403 means "I know who you are, but you aren't allowed here."
Generic 500 Errors: Avoid letting raw Java exceptions leak to the client. Catch them and return a meaningful status code or a clean 500 message.

Interview Notes for Developers

Question: What is the difference between 204 No Content and 404 Not Found?
Answer: 204 means the request was successful but there is nothing to send back (common in DELETE). 404 means the request failed because the resource does not exist.
Question: Which status code is used for an Idempotent request that results in no change?
Answer: Usually 200 OK or 204 No Content.
Question: Why is it important to use the correct status codes?
Answer: It improves API discoverability, allows client-side libraries to handle errors automatically, and follows the principles of the Richardson Maturity Model.

Summary

HTTP status codes are the backbone of communication in RESTful services. By using the correct codes—such as 201 Created for new resources, 400 Bad Request for validation errors, and 404 Not Found for missing data—you create an API that is predictable and easy for other developers to integrate with. Always aim for specificity to ensure the client knows exactly why a request succeeded or failed.

In the next lesson, we will explore Error Handling Best Practices to learn how to provide helpful error messages alongside these status codes.