This article covers HTTP status codes commonly used in REST APIs, including their meanings and best practices for using them in API development. By understanding these codes, developers can improve API reliability and provide clear guidance for client applications.

Categories of HTTP Status Codes

HTTP status codes are divided into five categories, each representing a different type of response:

  • 1xx Informational: Indicates that the request was received, and processing is continuing.
  • 2xx Success: Indicates that the request was successfully received, understood, and accepted.
  • 3xx Redirection: Indicates that further action is needed to complete the request, often involving a redirection to another URL.
  • 4xx Client Error: Indicates that there was an error with the request sent by the client.
  • 5xx Server Error: Indicates that the server encountered an error while processing the request.

Common HTTP Status Codes in REST APIs

2xx Success Codes

These codes signify that the client’s request was successfully processed.

  • 200 OK: The request was successful, and the server returned the requested resource. This is commonly used for GET requests.
  • 201 Created: Indicates that a new resource was created, typically used in response to POST requests.
  • 204 No Content: The request was successful, but there is no content to send in the response. Often used for DELETE requests.

3xx Redirection Codes

These codes suggest that the client needs to take additional action, usually involving redirection to a different URI.

  • 301 Moved Permanently: The requested resource has been moved to a new URI, and future requests should use this new URI.
  • 302 Found: The resource is temporarily located at a different URI.
  • 304 Not Modified: Indicates that the resource has not been modified since the last request, allowing the client to use cached data.

4xx Client Error Codes

These codes indicate an error caused by the client, often due to invalid requests.

  • 400 Bad Request: The request was invalid, often due to incorrect syntax or missing parameters.
  • 401 Unauthorized: The request requires authentication, and the client has not provided valid credentials.
  • 403 Forbidden: The client is authenticated but does not have permission to access the resource.
  • 404 Not Found: The requested resource could not be found on the server.
  • 409 Conflict: There is a conflict with the current state of the resource, often due to duplicate data.

5xx Server Error Codes

These codes indicate that the server encountered an error while trying to process the request.

  • 500 Internal Server Error: A generic error occurred on the server, often due to unhandled exceptions.
  • 502 Bad Gateway: The server received an invalid response from an upstream server while acting as a gateway or proxy.
  • 503 Service Unavailable: The server is temporarily unavailable, often due to overload or maintenance.
  • 504 Gateway Timeout: The server acting as a gateway or proxy did not receive a timely response from an upstream server.

Best Practices for Using Status Codes in REST APIs

1. Choose the Right Status Code for Each Outcome

Selecting the appropriate status code for each scenario improves API clarity and makes it easier for clients to handle responses. For example, use 201 Created after creating a resource and 204 No Content when a deletion is successful without returning any content.

2. Use 4xx Codes to Indicate Client Errors

4xx status codes help clients identify issues in their requests, such as missing parameters or insufficient permissions. Avoid using generic codes like 400 for every client error; instead, use specific codes to indicate the nature of the issue (e.g., 404 for missing resources, 403 for forbidden access).

3. Use 5xx Codes for Server-Side Errors

5xx status codes inform clients of server issues, such as temporary outages or unhandled exceptions. These codes should be accompanied by server logs to help diagnose and fix the problem. Avoid revealing detailed error information in the response to protect security.

4. Combine Status Codes with Error Messages

While status codes are useful, pairing them with informative error messages enhances usability. For example:

{
  "status": 400,
  "error": "InvalidRequest",
  "message": "The 'username' field is required and cannot be empty."
}

5. Use Caching Headers with 304 Not Modified

For resources that are rarely updated, consider using caching headers to allow clients to store data locally. When the resource hasn’t changed, respond with 304 Not Modified, indicating that the client can use cached data, improving performance and reducing server load.

Implementing Status Codes in Node.js with Express

Here’s an example of using status codes in an Express API:

const express = require('express');
const app = express();

app.get('/resource', (req, res) => {
  const resource = getResource();
  if (!resource) {
    return res.status(404).json({ status: 404, error: "NotFound", message: "Resource not found" });
  }
  res.status(200).json(resource);
});

app.post('/resource', (req, res) => {
  const newResource = createResource(req.body);
  res.status(201).json(newResource);
});

app.use((err, req, res, next) => {
  console.error(err);
  res.status(500).json({ status: 500, error: "InternalServerError", message: "An unexpected error occurred." });
});

This example shows how to use 404 for missing resources, 201 for created resources, and 500 for unexpected server errors.

Conclusion

Understanding and using HTTP status codes correctly is vital for developing clear and reliable REST APIs. By providing clients with accurate feedback on the outcome of their requests, status codes enable better error handling, smoother interactions, and enhanced usability. Following best practices for status codes helps create an API that’s intuitive, predictable, and easy to troubleshoot.