What HTTP Status Code to Return

Author:
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

  1. Retrieve an Employee by ID:

    • Method: GET
    • URL: /api/v1/employees/100
    • Return HTTP Status Code: 200 OK

  2. Retrieve All Employees:

    • Method: GET
    • URL: /api/v1/employees
    • Return HTTP Status Code: 200 OK

  3. Create a New Employee:

    • Method: POST
    • URL: /api/v1/employees
    • Return HTTP Status Code: 201 Created

  4. 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.

Comments

Post a Comment

Leave Comment