What are HTTP status codes?

The Postman Team

September 19, 2023

HTTP status codes are three-digit codes that indicate the outcome of an API request. They are included in the API’s response to the API client, and they include important information that helps the client know how to proceed.

HTTP status codes are essential to the HTTP protocol, which defines how data is transferred between clients and servers on the internet. Anyone who works with web-based technologies should have a solid understanding of these codes, as they provide valuable insight that can be used to troubleshoot issues and improve the user experience.

Here, we’ll explore the different types of HTTP status codes, highlight the most common ones, and discuss some best practices for implementing them.

Related: What is HTTP?

What are the different types of HTTP status codes?

HTTP status codes are grouped into five classes, each beginning with a number that represents the type of response. The classes are:

1xx informational responses

These codes indicate that the server has received the request and is processing it. They are primarily used to manage communication between the client and server during the early stages of a request-response cycle. Some examples of this type of code are:

• 100 Continue: This status code indicates that the initial part of the request has been received and the server would like the client to send the rest of it.
• 101 Switching Protocols: This status code is used to inform the client that the server is changing the protocol that is being used in the connection.
• 102 Processing: This status code is an interim response that indicates the server is still processing the request.

2xx success responses

These codes indicate that the client’s request was successfully received, understood, and processed by the server. Some of the most common 200 responses are:

• 200 OK: This status code indicates that the request was successful, and the server returned the requested data.
• 201 Created: This status code means that the request was successful, and the server created a new resource.
• 204 No Content: This status code indicates that the request was successful, but the server did not return any data.

3xx redirection responses

These codes indicate that the client needs to take additional actions to fulfill the request. They are often used when the requested resource has moved to a different location. Some examples include:

• 301 Moved Permanently: This status code indicates that the requested resource has been permanently moved to a new URL. Clients should respond by updating their bookmarks and links to point to the new URL, and search engines should update their indexes with the new location.
• 303 See Other: This status code indicates that the response is available at a different URL, and the client should perform a GET request to that URL to retrieve the resource.

4xx client error responses

These codes indicate that there was an issue with the client’s request, such as a mistyped URL or invalid credentials. The most common 4xx responses include:

• 400 Bad Request: This status code indicates that the request was malformed or invalid.
• 401 Unauthorized: This status code lets the client know that it is not authorized to access the requested resource.
• 403 Forbidden: This status code communicates that the client is authenticated but not authorized to access the requested resource.
• 404 Not Found: This status code indicates that the requested resource was not found on the server.

5xx server error responses

These codes, which indicate that the server encountered an error while trying to fulfill the client’s request, include:

• 500 Internal Server Error: This generic error code indicates the server encountered an unexpected condition that prevented it from fulfilling the request.
• 502 Bad Gateway: This status code indicates that a server acting as a gateway or proxy received an invalid response from an upstream server.
• 503 Service Unavailable: This status code is returned when the server is temporarily unable to handle the request. It’s often seen during periods of increased traffic or when the server is undergoing maintenance.

What are some best practices for working with HTTP status codes?

In order to implement HTTP status codes, developers must first identify the outcome of each request scenario to every API endpoint. They must then write logic for these scenarios, including the appropriate codes within each corresponding method. Status code implementation is an essential aspect of API development, so it’s important to adhere to the following best practices:

• Choose appropriate status codes: Select specific status codes that accurately reflect the outcome of the request. For instance, do not use 400 Bad Request when a requested resource cannot be found, as 404 Not Found is a more accurate representation of that outcome.
• Include meaningful response bodies when there’s an error: When the request cannot be fulfilled, the server should return a meaningful response body that includes details about the error. This helps the client understand what went wrong so that it can try to rectify the issue. You might also consider implementing custom error codes that represent application-specific errors.
• Use redirection codes appropriately: When using redirection codes (3xx), ensure that the resource’s new location is provided in the response headers. This practice helps maintain a consistent user experience and plays an important role in SEO.
• Keep sensitive data secure: Always avoid exposing sensitive information in error responses. Instead, provide general error messages without revealing implementation details or API security vulnerabilities.
• Provide thorough, up-to-date documentation: It’s essential to provide a clear run-down of your API’s status codes in your API documentation. You should also clearly document any status code-related changes as part of your API versioning strategy. This will help ensure that clients understand how to interpret and handle different responses, even as the API evolves.
• Test edge cases: Your API testing strategy should address various edge cases to confirm that your API is returning the appropriate status codes. For instance, you should test how your API handles invalid requests, server errors, and authentication-related issues.