HTTP Status Codes in ASP.NET Core Web API

HTTP Status Code in ASP.NET Core Web API

In this article, I will discuss HTTP Status Codes in ASP.NET Core Web API. Returning the response with a proper status code is the backbone of any restful Web API. Now, it is time to learn how to format the response with the proper response code as per our business requirements.

HTTP Status Codes:

The HyperText Transport Protocol status code is one of the important components of HTTP Response. HTTP status codes are standardized responses that a web server sends to a client (such as a browser or a mobile app) to indicate the outcome of a requested operation. These codes are part of the HTTP (Hypertext Transfer Protocol), which is the foundation of data communication on the World Wide Web. HTTP status codes are grouped into five categories, each defined by the first digit of the code, as follows. Here, XX will represent the actual number.

  • 1xx (Informational): These codes indicate a provisional response, and the request is still being processed. For example, 100 Continue means that the initial part of a request has been received and has not yet been rejected by the server.
  • 2xx (Successful): This range indicates that the client’s request was successfully received, understood, and accepted. For instance, 200 OK is the standard response for successful HTTP requests, and 201 Created indicates that the request has led to creating a new resource. 204 status code is also for success, but it does not return anything in return, just like if the client has performed a delete operation.
  • 3xx (Redirection): These codes tell the client that further action needs to be taken to complete the request. For example, 301 Moved Permanently indicates that the requested resource has been permanently moved to a new URL, and the client should use this new URL in the future.
  • 4xx (Client Error): This category signifies that the client seems to have erred. Whenever you get 4XX as the response code, it means there is some problem with your request. For example, 404 Not Found is one of the most recognizable codes, indicating that the server can’t find the requested resource. Another example is 400 Bad Request, meaning the server cannot process the request due to a client error. 401 is Unauthorized, which means the client has provided invalid authentication credentials. The 403 HTTP Status code means that authentication is successful, but the user is not authorized.
  • 5xx (Server Error): 5XX HTTP status codes are meant for Server Error. Whenever you get 5XX as the response code, it means there is some problem in the server. 500 Internal Server Error is a generic error message when an unexpected condition is encountered, and 503 Service Unavailable means that the server is not ready to handle the request, often due to maintenance or overload.
Frequently used HTTP Status Codes in ASP.NET Core Web API:

Here are some of the most frequently used HTTP status codes in ASP.NET Core Web API, along with their significance:

Successful Responses
  • 200 OK – The HTTP 200 OK success status response code indicates that the request has succeeded. This is often used for GET and POST requests that are processed successfully.
  • 201 Created – The request has succeeded, and a new resource has been created as a result. This is typically used in response to a POST request.
  • 202 Accepted– The 202 Status Code indicates that the request has been accepted for processing, but the processing has not been completed. 
  • 204 No Content – The server successfully processed the request but is not returning any content. This is often used for DELETE requests.
Redirection Messages
  • 301 Moved Permanently – This response code indicates that the URI of the requested resource has been changed permanently. Future requests should use the new URI.
  • 302 Found: This response code indicates that the resource is temporarily under a different URI. As the redirection might be altered occasionally, the client should continue using the original URI for future requests.
Client Error Responses
  • 400 Bad Request – The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax).
  • 401 Unauthorized – Although the HTTP standard specifies “unauthorized”, semantically, this response means “unauthenticated”. That is, the client must authenticate itself to get the requested response.
  • 403 Forbidden – The client does not have access rights to the content; that is, it is unauthorized, so the server refuses to give the requested resource. Unlike 401, the client’s identity is known to the server.
  • 404 Not Found – The server can not find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid, but the resource itself does not exist.
  • 405 Method Not Allowed – The 405 Method Not Allowed response status code indicates that the server knows the request method but is not supported by the target resource. For example, we have one method which is a POST method in the server and we trying to access that method from the client using GET Verb, then, in that case, you will get a 405-status code.
Server Error Responses
  • 500 Internal Server Error – The server has encountered a situation it doesn’t know how to handle.
  • 501 Not Implemented – The server either does not recognize the request method or lacks the ability to fulfil the request.
  • 503 Service Unavailable – The server is not ready to handle the request. Common causes include a server that is down for maintenance or overloaded.
  • 504 Gateway Timeout. The 504 Gateway Timeout server error response code indicates that the server while acting as a gateway or proxy, did not get a response in time from the upstream server that is needed to complete the request.

In ASP.NET Core Web API, these status codes can be returned explicitly by using the StatusCode method in a controller action or by returning a specific result type like Ok(), NotFound(), Created(), Accepted(), BadRequest(), etc., which encapsulates these HTTP status codes. From our next article, will discuss how to return these status codes from the controller action method.

Why HTTP Status Codes are Important?

If we want to consume any Restful API, we will send an HTTP Request, and in return, we will get the response, which includes data and an HTTP Status code. The HTTP Status codes are important because they tell the client (client who initiates the request, for example, Web, Android, iOS, Postman, IoT, Fiddler, etc) about what exactly happened to the request. If you send the wrong HTTP Status code, that will confuse the client, i.e., the API consumer.

HTTP status codes are crucial for several reasons, primarily for effective communication between a client (usually a web browser) and a server. These codes are part of the HTTP (Hypertext Transfer Protocol) response that a server sends back to the client in response to a request. Understanding why they are important involves recognizing their roles in web communication, troubleshooting, and user experience. Here are the key reasons:

  • Communication Clarity: HTTP status codes provide a standardized way for servers to tell clients about the requested action’s status. They help identify whether a request has been successfully processed, if there was an error, if further action is needed from the client, or if the request cannot be processed.
  • Efficient Troubleshooting: When something goes wrong with a web request, HTTP status codes can help quickly identify the problem. For example, a 404 Not Found status indicates that the requested resource could not be found on the server, while a 500 Internal Server Error suggests a problem with the server’s software or systems.
  • User Experience: By appropriately handling HTTP status codes, developers can provide users with more informative error messages or redirect them to alternative content, significantly improving the user experience. For example, a website can show a custom 404 page instead of a generic error page with links to help users find what they are looking for.
  • SEO Optimization: Search engines use HTTP status codes to understand website structure and content availability. For example, using 301 (Moved Permanently) status codes can help maintain SEO rankings when content is moved to a new URL. Conversely, too many 404 errors might negatively impact a site’s ranking.
  • Security: Certain HTTP status codes can indicate security issues. For instance, a 401 Unauthorized status code might alert administrators to unauthorized access attempts, while a 403 Forbidden status can be used to deny access to specific resources intentionally.

In our next article, we will discuss how to return 200 HTTP Status Codes in ASP.NET Core Web API. In this article, I will try to give an overview of the HTTP Status Codes in ASP.NET Core Web API.

Leave a Reply

Your email address will not be published. Required fields are marked *