HTTP Status Codes: The Ones You Actually Need to Know

Introduction

As a developer, working with HTTP status codes is a daily task. While there are numerous status codes, only a subset is used regularly. In this article, I will cover the most commonly used HTTP status codes, providing examples of when to use each.

Successful Requests

The 2xx status codes indicate that a request was successful. The following are the most commonly used:

200 OK

The 200 status code indicates that a request was successful and the response body contains the requested data.

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.

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

{
  "name": "John Doe"
}
HTTP/1.1 201 Created
Location: /users/1

204 No Content

The 204 status code indicates that a request was successful, but there is no content to return.

DELETE /users/1 HTTP/1.1
HTTP/1.1 204 No Content

Redirection

The 3xx status codes indicate that a request needs to be redirected. The following are the most commonly used:

301 Moved Permanently

The 301 status code indicates that a resource has been permanently moved to a new location.

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

304 Not Modified

The 304 status code indicates that a resource has not been modified since the last request.

GET /users HTTP/1.1
If-None-Match: "123456"
HTTP/1.1 304 Not Modified

Client Errors

The 4xx status codes indicate that a request was invalid or cannot be processed. The following are the most commonly used:

400 Bad Request

The 400 status code indicates that a request was invalid or malformed.

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

{
  "name": ""
}
HTTP/1.1 400 Bad Request

401 Unauthorized

The 401 status code indicates that a request requires authentication.

GET /users 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, even if the user is authenticated.

GET /admin HTTP/1.1
HTTP/1.1 403 Forbidden

404 Not Found

The 404 status code indicates that a resource was not found.

GET /users/999 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.

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

{
  "name": "John Doe"
}
HTTP/1.1 409 Conflict

422 Unprocessable Entity

The 422 status code indicates that a request was well-formed but cannot be processed due to semantic errors.

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

{
  "name": ""
}
HTTP/1.1 422 Unprocessable Entity

429 Too Many Requests

The 429 status code indicates that a user has exceeded the rate limit.

GET /users HTTP/1.1
HTTP/1.1 429 Too Many Requests

Server Errors

The 5xx status codes indicate that a server encountered an error. The following are the most commonly used:

500 Internal Server Error

The 500 status code indicates that a server encountered an unexpected error.

GET /users HTTP/1.1
HTTP/1.1 500 Internal Server Error

502 Bad Gateway

The 502 status code indicates that a server received an invalid response from an upstream server.

GET /users HTTP/1.1
HTTP/1.1 502 Bad Gateway

503 Service Unavailable

The 503 status code indicates that a server is currently unavailable.

GET /users HTTP/1.1
HTTP/1.1 503 Service Unavailable

Practical Takeaways

When working with HTTP status codes, it is essential to understand the meaning and usage of each code. By using the correct status code, you can provide a better user experience and improve the maintainability of your API. Remember to handle errors and exceptions properly, and always return a meaningful response to the client. Use the status codes outlined in this article to ensure that your API is robust and reliable.