What HTTP Status Code to Return

In this post, we will learn what HTTP status code to return from a REST API.

Previous Posts in the Series

When a client makes a request to a server through an API, the client needs feedback to know if the request succeeded, failed, or was invalid.

HTTP Status Codes

HTTP response codes are three-digit numbers that provide information about the status of a request made to a web server. They help indicate whether the request was successful and, if not, why not.

Success Category (2xx)

These status codes indicate that the requested action was successfully received and processed by the server.

200 OK: The request has succeeded. This status code is returned for successful GET, POST, PUT, and DELETE requests.
201 Created: The request has been fulfilled, and a new resource has been created. This is typically used for POST requests.
202 Accepted: The request has been accepted for processing, but the processing is not complete.
203 Non-Authoritative Information: The request was successful, but the information may be from a third party.
204 No Content: The server successfully processed the request, but there is no content to return. Often used for DELETE requests.
205 Reset Content: The server processed the request successfully, and the client should reset the document view.

Redirection Category (3xx)

These status codes indicate that further action is needed to complete the request.

300 Multiple Choices: The server has multiple options for the resource that the client can choose from.
301 Moved Permanently: The resource has been permanently moved to a new URI.
302 Found: The resource has been temporarily moved to a new URI.
304 Not Modified: The resource has not been modified since the last request, and the client can use the cached version.

Client Error Category (4xx)

These status codes indicate that the client has made an error.

400 Bad Request: The server could not understand the request due to invalid 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.
404 Not Found: The server cannot find the requested resource.
405 Method Not Allowed: The request method is not supported for the requested resource.
406 Not Acceptable: The requested resource is only capable of generating a response that is not acceptable according to the Accept headers sent in the request.
408 Request Timeout: The server timed out waiting for the request.
413 Payload Too Large: The request is larger than the server is willing or able to process.
415 Unsupported Media Type: The request entity has a media type that the server or resource does not support.
429 Too Many Requests: The client has sent too many requests in a given amount of time.

Server Error Category (5xx)

These status codes indicate that the server failed to fulfill a valid request.

500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.
501 Not Implemented: The server does not support the functionality required to fulfill the request.
502 Bad Gateway: The server received an invalid response from an upstream server.
503 Service Unavailable: The server is currently unable to handle the request due to a temporary overload or maintenance.
504 Gateway Timeout: The server did not receive a timely response from an upstream server.

Case Study 1: Employee Management System

Example Scenarios and Status Codes

Retrieve an Employee by ID:
- Method: GET
- URL: /api/v1/employees/100
- Return HTTP Status Code: 200 OK
Retrieve All Employees:
- Method: GET
- URL: /api/v1/employees
- Return HTTP Status Code: 200 OK
Create a New Employee:
- Method: POST
- URL: /api/v1/employees
- Return HTTP Status Code: 201 Created
Update an Employee by ID:
- Method: PUT
- URL: /api/v1/employees/100
- Return HTTP Status Code: 204 No Content

Case Study 2: User Management Application

Example REST APIs and Status Codes

GET /api/users - Retrieves all users: 200 OK
POST /api/users - Creates a new user: 201 Created
GET /api/users/{id} - Retrieves a user by ID: 200 OK
PUT /api/users/{id} - Updates a user by ID: 204 No Content
DELETE /api/users/{id} - Deletes a user by ID: 204 No Content

Conclusion

In this post, we learned about the appropriate HTTP status codes to return from a REST API. It is crucial to return the correct HTTP status code to provide meaningful feedback to the client.

Complete List of HTTP Status Codes

1XX Informational

100 Continue
101 Switching Protocols
102 Processing
103 Early Hints

2XX Successful

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information
204 No Content
205 Reset Content
206 Partial Content
207 Multi-Status
208 Already Reported
226 IM Used

3XX Redirection

300 Multiple Choices
301 Moved Permanently
302 Found
303 See Other
304 Not Modified
305 Use Proxy
306 Switch Proxy
307 Temporary Redirect
308 Permanent Redirect

4XX Client Error

400 Bad Request
401 Unauthorized
402 Payment Required
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
407 Proxy Authentication Required
408 Request Timeout
409 Conflict
410 Gone
411 Length Required
412 Precondition Failed
413 Payload Too Large
414 URI Too Long
415 Unsupported Media Type
416 Range Not Satisfiable
417 Expectation Failed
418 I’m a Teapot
421 Misdirected Request
422 Unprocessable Entity
423 Locked
424 Failed Dependency
425 Too Early
426 Upgrade Required
428 Precondition Required
429 Too Many Requests
431 Request Header Fields Too Large
451 Unavailable for Legal Reasons

5XX Server Error

500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates
507 Insufficient Storage
508 Loop Detected
510 Not Extended
511 Network Authentication Required

By understanding the appropriate HTTP status codes to return from your REST API, you can provide clear and useful feedback to clients, enhancing the overall functionality and user experience of your web services.

Java Guides

Search This Blog