Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 25

Mastering HTTP Status Codes

Recommended resources

Hello! Welcome back to our journey into backend development.

In the last lesson, we focused on the "verbs" of our API—the HTTP methods like GET, POST, and PUT that tell the server what action to perform. Now, we need to learn how the server communicates the outcome of that action back to the client.

This lesson completes the fundamental request-response cycle by focusing on HTTP status codes. These three-digit codes are the server's primary way of telling the client whether a request was successful, if there was an error, or if further action is needed. Using them correctly is essential for building predictable and easy-to-use APIs.

By the end of this lesson, you will be able to use standard HTTP status codes to accurately communicate API response states.

1. What Are HTTP Status Codes?

Every time a client (like a browser or a mobile app) sends a request to a server, the server includes a status code in its response. You've likely seen the most famous one: 404 Not Found. But there are many more, and they are organized into five distinct categories.

To get a clear overview of what status codes are and how they are categorized, please watch the first few minutes of the following video.

HTTP Status code in API Testing | 100, 200, 300, 400 and 500 Series status code Explained

This video from Software Testing And Automation provides a great introduction to HTTP status codes and their five main categories.

Watch from 01:16 to 04:04. This will explain what status codes are, why they matter, and the high-level meaning of each category (1xx, 2xx, 3xx, 4xx, 5xx).

As the video explained, these codes are grouped by their first digit:

  • 1xx (Informational): The request was received and is being processed. You will rarely use these directly in API development.
  • 2xx (Success): The request was successfully received, understood, and accepted. This is what you aim for!
  • 3xx (Redirection): Further action needs to be taken by the client to complete the request. These are more common in web browsing than in direct API calls.
  • 4xx (Client Error): The request contains bad syntax or cannot be fulfilled. The client did something wrong.
  • 5xx (Server Error): The server failed to fulfill an apparently valid request. Something went wrong on the server's end.

The following cheat sheet is an excellent visual summary of the most common codes you'll encounter.

HTTP Status Codes Cheat Sheet
This cheat sheet provides a quick reference for the most common HTTP status codes across the Success, Redirection, Client Error, and Server Error categories.

2. The Most Important Codes for API Development

While there are many status codes, you'll find yourself using a small subset of them over and over again. Let's focus on the essentials for a backend developer.

For a detailed walkthrough of the most common codes in the 2xx, 4xx, and 5xx series, please continue with the video from the previous section.

HTTP Status code in API Testing | 100, 200, 300, 400 and 500 Series status code Explained

This next part of the video dives into the specific codes that are critical for API development, providing clear examples for each.

Watch the following segments: 2xx Success (06:14 - 08:33): Focus on 200, 201, and 204. 4xx Client Errors (09:16 - 13:08): Pay close attention to 400, 401, 403, and 404. 5xx Server Errors (13:08 - 15:16): Understand 500 and 503. You can skip the sections on 1xx and 3xx as they are less common in this context.

Let's consolidate what you've just learned.

2xx Success Codes

  • 200 OK: The all-purpose "everything worked" code. It's the standard response for a successful GET or PUT. The response body typically contains the requested or updated resource.
  • 201 Created: Used specifically after a POST request that results in the creation of a new resource. The response should also include a Location header pointing to the URL of the newly created resource.
  • 204 No Content: Indicates the request was successful, but there's no data to return in the response body. This is the perfect code for a successful DELETE operation.

4xx Client Error Codes

This is where you communicate problems with the client's request.

  • 400 Bad Request: A generic error for when the client's request is malformed. Common causes include invalid JSON, missing required fields, or failed validation (e.g., an email address in the wrong format).
  • 401 Unauthorized vs. 403 Forbidden: This is a crucial distinction.
    • 401 Unauthorized means the client needs to authenticate (i.e., log in). They haven't provided valid credentials, or any at all.
    • 403 Forbidden means the client is authenticated, but they do not have the necessary permissions to access the resource. They are logged in, but they are not an admin, for example.
  • 404 Not Found: The server could not find the requested resource. This is used when a client asks for a specific URL (e.g., /users/999) and that resource doesn't exist.
  • 409 Conflict: The request could not be completed because of a conflict with the current state of the resource. A common example is trying to create a user with an email address that already exists in the database.

5xx Server Error Codes

These codes indicate a problem on your end, not the client's.

  • 500 Internal Server Error: A generic "something went wrong" on the server. This is a catch-all for unexpected exceptions in your code (e.g., a NullPointerException, a database connection failure). You should always log these errors for later debugging.

3. Connecting HTTP Methods to Status Codes

Now, let's tie this lesson together with the previous one. Each HTTP method you learned about has a set of expected success and error codes. Understanding this relationship is key to designing a logical and predictable API.

The following table, based on common REST conventions, provides a practical guide.

HTTP Method Operation Common Success Codes Common Error Codes
GET Retrieve a resource 200 OK (with data), 204 No Content (if search finds nothing) 404 Not Found
POST Create a new resource 201 Created 400 Bad Request, 409 Conflict
PUT Replace a resource 200 OK (if updating), 201 Created (if creating), 204 No Content (if updating & returning nothing) 400 Bad Request, 404 Not Found
PATCH Partially update a resource 200 OK 400 Bad Request, 404 Not Found, 409 Conflict
DELETE Remove a resource 204 No Content 404 Not Found
Test your understanding!

You are building an API for a blog. For each scenario, what is the most appropriate HTTP status code to return?

  1. A client sends a GET /posts/123 request, and post 123 exists.
  2. A client sends a POST /posts request with a valid new post, and it is successfully saved to the database.
  3. A client sends a DELETE /posts/456 request, and the post is successfully removed.
  4. A client sends a GET /posts/999 request, but no post with that ID exists.
  5. A client sends a POST /posts request but forgets to include the required title field in the JSON body.
Show answer
  1. 200 OK. The request was successful and you are returning the post data.
  2. 201 Created. A new resource was successfully created. You should also include a Location header pointing to /posts/{new-id}.
  3. 204 No Content. The deletion was successful, and there is no need to return any data.
  4. 404 Not Found. The specific resource the client asked for does not exist.
  5. 400 Bad Request. The client's request is invalid because it failed validation (a required field is missing).

4. Implementation in Spring Boot: ResponseEntity

So far, this has been theoretical. How do you actually control the status code in a Spring Boot application? The primary tool is the ResponseEntity class.

ResponseEntity is a powerful class that gives you complete control over the HTTP response. You can use it to set the status code, headers, and the response body all at once.

The following article provides a clear guide with practical code examples.

The Ultimate Guide to HTTP Status Codes in REST APIs

This guide demonstrates how to use ResponseEntity in Spring Boot to return different status codes for various API operations. The code snippets are clear and directly applicable.

Read the section titled 'Practical Examples with Spring Boot'. Focus on how different methods of the ResponseEntity builder (ok(), created(), noContent(), notFound()) correspond to the status codes we've just discussed.

As you saw in the article, Spring provides convenient static methods to create ResponseEntity objects:

  • ResponseEntity.ok(body) returns a 200 OK with a response body.
  • ResponseEntity.created(uri).body(body) returns a 201 Created.
  • ResponseEntity.noContent().build() returns a 204 No Content.
  • ResponseEntity.notFound().build() returns a 404 Not Found.
  • ResponseEntity.badRequest().build() returns a 400 Bad Request.

Using ResponseEntity in your controllers is the standard, professional way to handle API responses in Spring.

Conclusion

Great job! You now understand the final part of the basic request-response cycle. By combining clear URIs (the nouns), appropriate HTTP methods (the verbs), and precise HTTP status codes (the feedback), you can design APIs that are robust, predictable, and easy for other developers to work with.

Key Takeaways:

  • HTTP status codes are the server's way of communicating the outcome of a request.
  • Codes are grouped into five series: 1xx (Informational), 2xx (Success), 3xx (Redirection), 4xx (Client Error), and 5xx (Server Error).
  • For API development, the most important codes are:
    • Success: 200 OK, 201 Created, 204 No Content
    • Client Error: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
    • Server Error: 500 Internal Server Error
  • In Spring Boot, you use the ResponseEntity class to control the status code of your responses.

What's Next?

A status code like 400 Bad Request is a great start, but it doesn't tell the client why their request was bad. Was a field missing? Was a value out of range? In our next lesson, we will focus on how to design consistent and predictable JSON payloads, especially for error responses, to provide clients with the rich, detailed feedback they need to fix their requests.