Returning HTTP Status Codes: an overview

Why the default status codes (200 on success, 500 on any error) aren't enough, shown by a request for a category that doesn't exist and still gets 200.

Apprentice · Spring Boot · REST API · Updated

By

By default, the web methods of a @RestController return a status code of 200 when they have completed their work. If an error occurs, a status code of 500 is returned.

In the POST lesson, we added a @ResponseStatus annotation to the API methods that should return a different success status code.

@PostMapping(path="/api/categories")
@ResponseStatus(value = HttpStatus.CREATED)
public Category addCategory (@RequestBody Category category)
{
  return categoryDao.insert(category);
}

However, this only addresses the status code that is returned if the method call is successful. If the method fails, i.e. if there is an error, the API call will return a status code of 500, or server error.

We want to have more fine-grained control over the status code returned by our methods.

Valid Request

A request for a category with a valid category ID - we would expect a status code of 200 - success.

GET http://localhost:8080/api/categories/8
@GetMapping(path="/api/categories/{id}")
public Category getCategoryById(@PathVariable int id)
{
  //use the DAO to get the category by id
  return categoryDao.getCategoryById(id);
}

The server would return:

HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 19 Sep 2024 14:11:33 GMT

{
  "categoryId": 8,
  "categoryName": "Seafood",
  "description": "Seaweed and fish"
}

Invalid Request

But what if a user requests a category ID that does not exist?

Consider this request:

GET http://localhost:8080/api/categories/300
@GetMapping(path="/api/categories/{id}")
public Category getCategoryById(@PathVariable int id)
{
  //use the DAO to get the category by id
  return categoryDao.getCategoryById(id);
}

The API will still return status code 200 - success, but the DAO will have returned null so that the response body will be empty.

HTTP/1.1 200
Content-Length: 0
Date: Thu, 19 Sep 2024 14:07:38 GMT

We need finer control.

Do it: predict the status code Spring Boot sends

Before you take control of the status codes, it helps to know exactly what Spring Boot sends when you don't. Write a method that predicts it, from the two things that decide it: the method's @ResponseStatus annotation, if it has one, and whether the method threw an exception.

The method gets two values:

  • responseStatus: the code in the method's @ResponseStatus annotation, an int, such as 201 for HttpStatus.CREATED. It's 0 when the method has no @ResponseStatus.
  • threw: true when the method threw an exception, false when it finished its work.

For example, GET /api/categories/300: getCategoryById has no @ResponseStatus, and it doesn't throw (the DAO returns null, and the method returns it):

Question For GET /api/categories/300
Did the method throw? no
Does it have a @ResponseStatus? no: 0
The status sent 200, even though there's no category 300

So defaultStatus(0, false) returns 200.

Your job: write the method defaultStatus(int responseStatus, boolean threw) so it returns the status code Spring Boot sends, an int.

  • When the method threw, return 500, whatever its @ResponseStatus says: the annotation only covers success.
  • Otherwise, when it has a @ResponseStatus (responseStatus isn't 0), return that code.
  • Otherwise, return 200.

Practiced live on the lesson page: write the Java right there and check it.

Cheat sheets