Skip to main content

HTTP Status Codes

HTTP status codes are how your server talks back to a client. Every browser load, mobile app call, or REST API request ends with one of these numbers. If you read them correctly, they tell you whether things worked, failed, or need another step.

This guide explains HTTP status codes from a developer’s point of view. You will understand what they mean, where they appear in real responses, and how to use them correctly when building or testing APIs.

What are HTTP status codes​

HTTP status codes are part of every HTTP response. They live in the response status line and describe the outcome of a request in a compact, standard way.

A typical response starts like this:

HTTP/1.1 200 OK

That single line already answers three questions:

  • Which HTTP version was used
  • Whether the request succeeded or failed
  • What kind of outcome the server produced

Everything else in the response body depends on this code being interpreted correctly by the client.

Where status codes appear in real responses​

Here is a simplified raw HTTP response envelope:

HTTP/1.1 200 OK
Date: Sun, 03 Dec 2023 12:00:00 GMT
Server: Apache/2.4.1 (Unix)
Content-Type: text/html; charset=UTF-8
Content-Length: 1234

<!DOCTYPE html>
<html>
  <body>
    <h1>Welcome</h1>
  </body>
</html>

The status code is not part of the JSON or HTML body. It lives in the protocol layer itself. This matters because clients often branch logic based on the code before even parsing the response body.

Common HTTP status codes​

Here are some popular examples of status codes with their uses.

  • 200 OK: This status code is used for successful GET, POST, PUT, or DELETE requests. For example, when a user requests a webpage (GET request), and the server successfully processes and returns the page, the response will typically have a 200 OK status code.

  • 201 Created: This indicates that a new resource has been successfully created, commonly used in response to POST requests. For instance, when a user submits a form to sign up for a service (POST request), and the server successfully creates a new user account, it responds with 201 Created.

  • 400 Bad Request: This status code indicates a general client error when the request sent to the server is invalid. An example is when a client submits a form with missing required fields, the server cannot process the request and responds with 400 Bad Request.

  • 401 Unauthorized: Used when authentication is required and has failed or has not been provided. For example, if a user tries to access a protected resource without proper authentication credentials, the server responds with 401 Unauthorized.

  • 403 Forbidden: This code indicates that the server understands the request but refuses to authorize it. A use case is when a user tries to access a resource they don’t have permission for, like an admin panel for regular users, resulting in a 403 Forbidden response.

  • 404 Not Found: Used when the requested resource is not found on the server. For instance, if a user tries to access a webpage that has been removed or never existed, the server responds with 404 Not Found.

  • 500 Internal Server Error: A generic error message for an unexpected condition encountered by the server. An example is when there’s a misconfiguration on the server or an error in the server-side script, leading to a 500 Internal Server Error response.

Implement and Test HTTP Status Codes

Create mock endpoints to simulate various HTTP status codes, test error scenarios, and validate your application's response handling.

Instant mock API creation • Test all status codes • No configuration needed

Classification of HTTP status codes​

HTTP status codes are divided into five categories, each signifying a specific type of response and responsibility:

1xx (Informational): These codes indicate a provisional response, primarily acknowledging the receipt of a request. For example, 100 Continue suggests that the initial part of a request has been received and the client should continue with the request.

2xx (Success): This category signifies that the client's request was successfully received, understood, and accepted. A common example is 200 OK, which indicates a successful request.

3xx (Redirection): These codes inform the client that further action needs to be taken to complete the request, often involving redirection to another URI. 301 Moved Permanently is a typical example, indicating that the requested resource has been permanently moved to a new location.

4xx (Client Error): This group represents errors where the client seems to have erred. This means, the same request should't be tried again without modification or as is. 404 Not Found is one of the most recognizable status codes, indicating that the server cannot find the requested resource. Besides giving a bad user experience, these status codes can also hurt your SEO efforts, if you are hosting a website.

5xx (Server Error): These codes are used when the server fails to fulfill a valid request. Typically a server bug, unhandled scenario or something that is unexpected and the server failed. As a service owner, if you're experiencing 5xx server errors for your API services, you should immediately look at your cause and address it. The 500 Internal Server Error is a common code in this category, indicating a generic error when no more specific message is suitable. There are more specific codes. These error codes are considered for Rest API availability calculation.

REST API Best Practices with Respect to Status Codes​

With the RESTful APIs, the HTTP status codes are bound tightly. These status codes not only convey the outcome of the client's request but also guide the client on the next steps to take. Here are some best practices for using HTTP status codes in REST APIs:

  • Choose Appropriate Status Codes: You should select the most specific status code for each response. This specificity helps clients understand exactly what happened with their request. For instance, use 201 Created for successfully created resources and 204 No Content when a request is successful but there's nothing to return.

  • Consistent Use of Status Codes: Apply status codes consistently across your API. Inconsistent use of status codes can lead to confusion and misinterpretation of the response by the client. E.g. using 200 OK for all success responses.

  • Use 2xx Series for Successful Operations: For all successful operations, use the 2xx series. Within this series, distinguish between different types of successes, like 200 OK for successful fetch operations, 201 Created for successful creation, and 202 Accepted for requests that have been accepted but are still processing.

  • Employ 4xx Series for Client Errors: Use 4xx series codes to indicate errors caused by the client. For example, 400 Bad Request for general client errors, 401 Unauthorized for authentication errors, and 404 Not Found when the requested resource does not exist.

  • Use 5xx Series for Server Errors: Utilize 5xx series codes for server-side issues. These indicate problems with the server that the client cannot resolve. For instance, 500 Internal Server Error for unexpected server issues and 503 Service Unavailable for temporary unavailability of the server.

  • Provide Clear Error Messages: In addition to the status code, provide a clear and descriptive error message in the response body. This message should give the client a clear understanding of what went wrong and, if possible, how to fix it.

  • Document Status Codes: Clearly document the status codes your API returns. This documentation should explain what each status code means in the context of your API and when each is used.

  • Avoid Overloading Status Codes: While it might be tempting to overload status codes with application-specific meanings, this can lead to confusion. Stick to the standard meanings as defined by the HTTP specification.

  • Handle Graceful Degradation: In cases where your API must change its behavior (e.g., deprecating endpoints), use status codes to indicate these changes gracefully, like 410 Gone for resources that used to exist but no longer do.

  • Monitor and Log Status Codes: Regularly monitor and log the status codes your API returns. This can help in identifying patterns, understanding the API's usage, and troubleshooting issues.

Using Beeceptor for Studying Status Codes​

Beeceptor, an API mocking tool, is an excellent platform for understanding and experimenting with HTTP status codes. Here’s how to use Beeceptor for this purpose:

  1. Create a Mock API: Start by creating a mock API endpoint in Beeceptor.
  2. Configure Responses: Set up different mock rules to return various HTTP status codes. You can simulate scenarios like successful requests, client errors, and server errors.
  3. Test and Observe: Use an HTTP client to send requests to your Beeceptor endpoints. Observe the responses and status codes returned.
  4. Experiment with Scenarios: Modify the request parameters and headers to see how different inputs affect the status codes returned by your mock API.
  5. Learn Through Practice: Use this hands-on approach to understand the nuances of HTTP status codes and how they should be handled in real-world scenarios.

HTTP status codes are the language your API speaks to clients. If you use them correctly, clients behave predictably and debugging becomes easier. If you misuse them, everything feels random.

Understand these groups, apply them at the right code for the right situation. Test for both success and failure paths. With tools like Beeceptor, you can practice and validate all of this without touching a real backend.