How can you choose the right HTTP status codes for a Spring Boot web service?

1 What are HTTP status codes?

HTTP status codes are three-digit numbers that are sent by the server along with the response to the client. They are divided into five categories based on the first digit: 1xx for informational, 2xx for success, 3xx for redirection, 4xx for client errors, and 5xx for server errors. Each category has a range of codes that represent different situations and messages. For example, 200 means OK, 301 means Moved Permanently, 404 means Not Found, and 500 means Internal Server Error.

3 How to choose the right HTTP status codes for success?

When your web service performs a successful operation, you should choose a 2xx code that reflects the nature and result of the operation. For example, if your web service creates a new resource, you should use 201 Created and include the location of the new resource in the Location header. If your web service updates an existing resource, you should use 200 OK and include the updated resource in the body. If your web service deletes a resource, you should use 204 No Content and omit the body.

5 How to choose the right HTTP status codes for client errors?

When your web service encounters an error that is caused by the client's request, you should use a 4xx code that identifies the error and provides a helpful message. For example, if your web service cannot find a resource that matches the request, you should use 404 Not Found and include a message that explains what resource was not found. If your web service cannot process the request because of a validation error, you should use 400 Bad Request and include a message that describes the validation error. If your web service cannot authorize the request because of a missing or invalid token, you should use 401 Unauthorized and include a message that instructs the client how to obtain a valid token.

6 How to choose the right HTTP status codes for server errors?

When your web service encounters an error that is caused by the server's internal logic, configuration, or dependency, you should use a 5xx code that indicates the severity and scope of the error. For example, if your web service fails to execute an operation because of an unexpected exception, you should use 500 Internal Server Error and include a message that summarizes the exception. If your web service fails to communicate with another service because of a network or timeout error, you should use 503 Service Unavailable and include a message that informs the client when the service might be available again. If your web service fails to support the request method or media type that the client uses, you should use 501 Not Implemented or 415 Unsupported Media Type and include a message that suggests an alternative method or media type.

7 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?