MEHDI.
RETURN_TO_INDEX

HTTP Status Codes: The Ones You Actually Need to Know

6 min read
#Backend#Web Development#HTTP#API

Introduction

As a developer, understanding HTTP status codes is crucial for building robust and maintainable applications. In this article, I will cover the most commonly used HTTP status codes that you need to know.

Successful Requests

The following status codes indicate that a request was successful.

200 OK

The 200 status code indicates that a request was successful and the response body contains the requested data. For example, when a user retrieves a list of users, the API should return a 200 status code with the list of users in the response body.

GET /users HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "name": "John Doe"
  },
  {
    "id": 2,
    "name": "Jane Doe"
  }
]

201 Created

The 201 status code indicates that a request was successful and a new resource was created. For example, when a user creates a new account, the API should return a 201 status code with the newly created account details in the response body.

POST /users HTTP/1.1
Content-Type: application/json

{
  "name": "John Doe",
  "email": "[email protected]"
}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /users/1

{
  "id": 1,
  "name": "John Doe",
  "email": "[email protected]"
}

204 No Content

The 204 status code indicates that a request was successful but there is no content to return. For example, when a user updates their profile information, the API should return a 204 status code if the update was successful.

PATCH /users/1 HTTP/1.1
Content-Type: application/json

{
  "name": "Jane Doe"
}

HTTP/1.1 204 No Content

Redirection

The following status codes indicate that a request needs to be redirected.

301 Moved Permanently

The 301 status code indicates that a request needs to be redirected to a new location permanently. For example, when a user requests a resource that has been moved to a new location, the API should return a 301 status code with the new location in the Location header.

GET /old-resource HTTP/1.1
HTTP/1.1 301 Moved Permanently
Location: /new-resource

304 Not Modified

The 304 status code indicates that a request needs to be redirected to a cached version of the resource. For example, when a user requests a resource that has not been modified since the last request, the API should return a 304 status code.

GET /resource HTTP/1.1
If-None-Match: "etag"

HTTP/1.1 304 Not Modified

Client Errors

The following status codes indicate that a request was invalid or cannot be processed.

400 Bad Request

The 400 status code indicates that a request was invalid or cannot be processed. For example, when a user sends a request with invalid data, the API should return a 400 status code with an error message in the response body.

POST /users HTTP/1.1
Content-Type: application/json

{
  "name": "John Doe"
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Email is required"
}

401 Unauthorized

The 401 status code indicates that a request requires authentication. For example, when a user requests a protected resource without being authenticated, the API should return a 401 status code.

GET /protected-resource HTTP/1.1

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="example"

403 Forbidden

The 403 status code indicates that a request is forbidden. For example, when a user requests a resource that they do not have permission to access, the API should return a 403 status code.

GET /protected-resource HTTP/1.1
Authorization: Bearer token

HTTP/1.1 403 Forbidden

404 Not Found

The 404 status code indicates that a request was not found. For example, when a user requests a resource that does not exist, the API should return a 404 status code.

GET /non-existent-resource HTTP/1.1

HTTP/1.1 404 Not Found

409 Conflict

The 409 status code indicates that a request conflicts with the current state of the resource. For example, when a user tries to update a resource that has been modified by someone else, the API should return a 409 status code.

PATCH /users/1 HTTP/1.1
Content-Type: application/json

{
  "name": "Jane Doe"
}

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": "Resource has been modified by someone else"
}

422 Unprocessable Entity

The 422 status code indicates that a request was well-formed but the data was invalid. For example, when a user sends a request with invalid data, the API should return a 422 status code with an error message in the response body.

POST /users HTTP/1.1
Content-Type: application/json

{
  "name": "John Doe"
}

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "Email is required"
}

429 Too Many Requests

The 429 status code indicates that a request was rate limited. For example, when a user sends too many requests in a short period of time, the API should return a 429 status code.

GET /resource HTTP/1.1

HTTP/1.1 429 Too Many Requests

Server Errors

The following status codes indicate that a request failed due to a server error.

500 Internal Server Error

The 500 status code indicates that a request failed due to an internal server error. For example, when a user requests a resource and the server encounters an unexpected error, the API should return a 500 status code.

GET /resource HTTP/1.1

HTTP/1.1 500 Internal Server Error

502 Bad Gateway

The 502 status code indicates that a request failed due to a bad gateway. For example, when a user requests a resource and the server acts as a gateway to another server, the API should return a 502 status code if the gateway server encounters an error.

GET /resource HTTP/1.1

HTTP/1.1 502 Bad Gateway

503 Service Unavailable

The 503 status code indicates that a request failed due to a service being unavailable. For example, when a user requests a resource and the server is overloaded or down for maintenance, the API should return a 503 status code.

GET /resource HTTP/1.1

HTTP/1.1 503 Service Unavailable

Practical Takeaways

When building APIs, it is essential to handle HTTP status codes correctly to ensure that clients can understand the outcome of their requests. Here are some practical takeaways:

  • Use 200, 201, and 204 status codes to indicate successful requests.
  • Use 301 and 304 status codes to handle redirection.
  • Use 400, 401, 403, 404, 409, 422, and 429 status codes to handle client errors.
  • Use 500, 502, and 503 status codes to handle server errors.
  • Always include a clear and descriptive error message in the response body when returning an error status code.
  • Consider using a standard error format, such as JSON API, to ensure consistency across your API.