501 HTTP Status Code in ASP.NET Core Web API

501 HTTP Status Code in ASP.NET Core Web API

In this article, I will discuss How to Return 501 Not Implemented HTTP Status Code in ASP.NET Core Web API Application with Examples. Please read our previous article discussing How to Return 500 Internal Server HTTP Status Code in ASP.NET Core Web API with Examples.

501 HTTP Status Code

The 501 HTTP Status Code is defined as “Not Implemented.” It indicates that the server does not support the functionality required to fulfill the request. This response is typically sent when the server lacks the ability to perform a particular action. For example, if a client sends a request method to the server that it does not know how to handle, such as a PUT or DELETE method that the server does not support for any resource, the server might respond with a 501 Status Code. Here are key points regarding the 501 Status Code:

  • Server Capability: The 501 Status Code signifies that the server either does not recognize the request method or lacks the capability to complete the request. It implies that the server itself might be capable of supporting the request in the future but currently does not.
  • Client Action: From a client’s perspective, receiving a 501 response typically means nothing wrong. Instead, the issue lies with the server’s ability to handle the request. The client may need to check the request method or consult with the server’s documentation or support to understand what methods are supported.
  • Temporary or Permanent: The nature of this error could be either temporary or permanent, depending on whether the server plans to implement the functionality in the future or if it intends never to support the specific request method or action.
How to Return 501 HTTP Status Code in ASP.NET Core Web API?

In the context of ASP.NET Core Web API, sending a 501 status code can be done explicitly within your controller actions or middleware components if you encounter a situation where the server is unable to perform a particular operation or if a certain feature is not yet implemented.

Using StatusCode Method

You can directly return the StatusCode from your actions by specifying the numeric value of the HTTP status code you want to return. For a better understanding, please modify the Sample Controller as follows. Let us assume we have shared the API signature with the client to send the Email service. However, we have not yet implemented the email service in our application. In situations like this, we need to return the 501 Not Implemented Status code to the client.

using Microsoft.AspNetCore.Mvc;

namespace ReturnTypeAndStatusCodes.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class SampleController : ControllerBase
    {
        //URL: GET api/Sample/SendEmail
        [HttpGet("SendEmail")]
        public IActionResult SendEmail()
        {
            var customResponse = new
            {
                Code = 501,
                Message = "Email Feature Is Not Implemented",
            };

            //Returning Not Implemented
            return StatusCode(StatusCodes.Status501NotImplemented, customResponse);
        }
    }
}

Now, access the above API Endpoint as https://localhost:7094/api/Sample/SendEmail, and you should get the following response.

501 HTTP Status Code in ASP.NET Core Web API

Custom ActionResult

If returning a 501 Status Code is common across different actions or controllers, you might consider creating a custom ActionResult for reuse. So, create a class file named NotImplementedResult.cs and then copy and paste the following code:

using Microsoft.AspNetCore.Mvc;
using System.Net;

namespace ReturnTypeAndStatusCodes.Models
{
    public class NotImplementedResult : IActionResult
    {
        public Task ExecuteResultAsync(ActionContext context)
        {
            var customResponse = new
            {
                Code = 501,
                Message = "Feature Is Not Implemented",
            };

            var objectResult = new ObjectResult(customResponse)
            {
                StatusCode = (int)HttpStatusCode.NotImplemented
            };

            return objectResult.ExecuteResultAsync(context);
        }
    }
}

In the above example,

  • IActionResult indicates that NotImplementedResult implements the IActionResult interface. Implementing this interface allows the class to be returned from an ASP.NET Core controller action. The IActionResult interface is used by the ASP.NET Core framework to handle HTTP responses.
  • public Task ExecuteResultAsync(ActionContext context) is the method that must be implemented from the IActionResult interface. This method is responsible for executing the action result asynchronously.
  • ActionContext context is a parameter that provides context information about the action being executed, including HTTP request and response objects.
  • customResponse is the object that we want to return to the client.
  • var objectResult = new ObjectResult(customResponse) creates a new instance of ObjectResult, which is another type of action result that represents a general-purpose response that includes a status code and custom error message.
  • { StatusCode = (int)HttpStatusCode.NotImplemented } sets the StatusCode property of the ObjectResult to 501, which is the numeric representation of the NotImplemented status code. This is achieved by casting HttpStatusCode.NotImplemented (an enumeration value) to an int.
  • return objectResult.ExecuteResultAsync(context); calls the ExecuteResultAsync method on the ObjectResult instance, passing in the ActionContext. This line effectively executes the result, causing ASP.NET Core to send an HTTP response with the status code 501 back to the client.

And then use it in your controller actions. So, modify the Sample Controller as follows:

using Microsoft.AspNetCore.Mvc;
using ReturnTypeAndStatusCodes.Models;

namespace ReturnTypeAndStatusCodes.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class SampleController : ControllerBase
    {
        //URL: GET api/Sample/SendEmail
        [HttpGet("SendEmail")]
        public IActionResult SendEmail()
        {
            return new NotImplementedResult();
        }
    }
}
When to Use or Return 501 HTTP Status Code in ASP.NET Core Web API

The 501 Not Implemented HTTP status code is used in ASP.NET Core Web API (or any web service environment) to indicate that the server does not support the functionality required to fulfill the request. This status is typically returned in situations where:

  • Features Not Supported: The server does not support certain features that are required to process the request. This could be due to missing functionalities that the API is expected to offer but hasn’t been developed or deployed yet.
  • Future Functionality: Sometimes, an API endpoint might be planned but not implemented. The 501 Status Code can be returned as a placeholder response to indicate that the requested resource is expected to be available in the future but isn’t right now.

In the next article, I will discuss How to Return 503 Service Unavailable HTTP Status Code in ASP.NET Core Web API with Examples. In this article, I try to explain How to Return 501 Not Implemented Error HTTP Status Code in ASP.NET Core Web API with Examples, and I hope you enjoy this article on “How to Return 501 Not Implemented Error HTTP Status Code in ASP.NET Core Web API”.

Leave a Reply

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