aspnet-core | api

ASP.NET Core - Return 500 (Internal Server Error) or any other Status Code from API

A good REST API will respond with proper HTTP status codes. In ASP.NET Core, returning status code is easier than you might think.

Abhith Rajan
Abhith RajanSeptember 16, 2019 · 2 min read · Last Updated:

HTTP response status codes have so much importance in REST API’s. In any case if you want to return a status code from your ASP.NET Core API, all you have to do is in your controller method,

return  StatusCode(StatusCodes.Status500InternalServerError);

StatusCode is from Microsoft.AspNetCore.Mvc.ControllerBase.StatusCode and StatusCodes from Microsoft.AspNetCore.Http.StatusCodes. The above code will return a 500 status code. Similar way, you can return any other status code. For the complete list,

👉 StatusCodes Class (Microsoft.AspNetCore.Http) | Microsoft Docs

HTTP status code 5xx indicates server error. 5xx series includes,

Status CodeDescriptionASP.NET Core 2.2
500Internal Server ErrorStatus500InternalServerError
501Not ImplementedStatus501NotImplemented
502Bad GatewayStatus502BadGateway
503Service UnavailableStatus503ServiceUnavailable
504Gateway TimeoutStatus504GatewayTimeout
505HTTP Version Not SupportedStatus505HttpVersionNotsupported
506Variant Also NegotiatesStatus506VariantAlsoNegotiates
507Insufficient StorageStatus507InsufficientStorage
508Loop DetectedStatus508LoopDetected
510Not ExtendedStatus510NotExtended
511Network Authentication RequiredStatus511NetworkAuthenticationRequired
599Network Connect Timeout Error

You can also return some additional data along with the status code. Here is an example,

[ProducesResponseType(typeof(Merchant), 200)]
public async Task<ActionResult> GetMerchant(string code)
    var input = new EntityRequestDto<string>
        Id = code

    var result = await _merchantService.GetMerchant(input);

    if (result.IsSuccess)
        return Ok(result.Value);

    _logger.LogError("FAILED: GetMerchant - ${result.Error}");
    return StatusCode(StatusCodes.Status500InternalServerError, result.Error);


If another service which is a client of the above API, they can get the additional info by,

public async Task<MerchantPreviewDto> GetMerchant(string merchantCode)
        var merchant = await $"{_apiBaseUri}/api/v1/merchants/{merchantCode}"

        return ObjectMapper.Map<MerchantPreviewDto>(merchant);
    catch (FlurlHttpException ex)
        var error = await ex.GetResponseStringAsync();
        throw new UserFriendlyException("Oops! There is a problem!", error);


On the client service, I am using Flurl, which is my favorite HTTP client.

Flurl is a modern, fluent, asynchronous, testable, portable, buzzword-laden URL builder and HTTP client library for .NET.

Which one is your favorite HTTP client library for .NET?

This page is open source. Noticed a typo? Or something unclear?
Improve this page on GitHub

Abhith Rajan

Written byAbhith Rajan
Abhith Rajan is a software engineer by day and a full-stack developer by night. He's coding for almost a decade now. He codes 🧑‍💻, write ✍️, learn 📖 and advocate 👍.


Is this page helpful?

Related ArticlesView All

Related VideosView All

Why I DON'T use MediatR in ASP.NET Core

Don't Use AutoMapper in C#! Do THIS Instead!

Exploring Source Generation for Logging

Related StoriesView All

Related Tools & ServicesView All


Flurl is a modern, fluent, asynchronous, testable, portable, buzzword-laden URL builder and HTTP client library for .NET.

HTTP Status Codes —

HTTP Status Code directory, with definitions, details and helpful code references.