How to return a 500 response in ASP.NET Core

For example:

[Route("[controller]")]
[ApiController]
public class BooksController : ControllerBase
{
    [HttpPost]
    public IActionResult Save(Book book)
    {
        return Problem();
    }
}

This method returns an ObjectResult with a 500 status code and a generic error message. The response will be serialized into a JSON format, which looks like this:

500 - Internal Server Error
Content-Type: application/problem+json

Body:
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
    "title": "An error occurred while processing your request.",
    "status": 500,
    "traceId": "0HMDLK1UAAP5O:00000002"
}

The ControllerBase class has several helper methods like Problem() that simplify returning responses. These helpers include optional parameters for customizing the response.

Customizing the 500 Response

The Problem() method has the following signature:

public ObjectResult Problem(string detail = null, 
                            string instance = null, 
                            int? statusCode = null, 
                            string title = null, 
                            string type = null);

You can pass values to these parameters to modify the response.

To change the status code, simply provide a value for the statusCode parameter.

For example, to return a 501 - Not Implemented response:

using Microsoft.AspNetCore.Http;

[Route("[controller]")]
[ApiController]
public class BooksController : ControllerBase
{
    [HttpPost]
    public IActionResult Save(Book book)
    {
        return Problem(statusCode: StatusCodes.Status501NotImplemented);
    }
}

This will generate the following response:

501 - Not Implemented
Content-Type: application/problem+json

Body:
{
    "status": 501,
    "traceId": "0HMDLKL0AFS4D:00000001"
}

You can either hardcode the status code (e.g., 501), use constants from StatusCodes, or use HttpStatusCode enums (casting them to integers).

You can use the detail parameter to provide more information about the error.

For example, you might want to include details about the missing book:

[Route("[controller]")]
[ApiController]
public class BooksController : ControllerBase
{
    [HttpPost]
    public IActionResult Save(Book book)
    {
        return Problem(detail: "Book not found.");
    }
}

This will produce the following response:

500 - Internal Server Error
Content-Type: application/problem+json

Body:
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
    "title": "An error occurred while processing your request.",
    "status": 500,
    "detail": "Book not found.",
    "traceId": "0HMDLKRP86VKE:00000001"
}

If you want full control over the response, bypass the default ProblemDetails format and use the StatusCode() helper method:

using Microsoft.AspNetCore.Http;

[Route("[controller]")]
[ApiController]
public class BooksController : ControllerBase
{
    [HttpPost]
    public IActionResult Save(Book book)
    {
        return StatusCode(StatusCodes.Status500InternalServerError, "Book not found.");
    }
}

This will generate the following response:

500 - Internal Server Error
Content-Type: text/plain

Body:
Book not found.

Building Custom Response Objects

ASP.NET Core provides helper methods for returning standardized result objects like StatusCodeResult or ObjectResult. You can also create custom response objects.

For example, to return a 500 response without any content, use ContentResult:

using Microsoft.AspNetCore.Http;

[Route("[controller]")]
[ApiController]
public class BooksController : ControllerBase
{
    [HttpPost]
    public IActionResult Save(Book book)
    {
        return new ContentResult()
        {
            StatusCode = StatusCodes.Status500InternalServerError
        };
    }
}

This generates the following response:

500 - Internal Server Error
Content-Length: 0

You can use various result types like StatusCodeResult, ContentResult, or ObjectResult based on your needs. In many cases, ContentResult works well.

ASP.NET Core offers helper methods for common status codes. However, for less common codes, you can use StatusCode() to return any code.

200 - OK

For returning a 200 – OK response, use the Ok() helper method. Here’s an example of returning a book's information:

[Route("[controller]")]
[ApiController]
public class BooksController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult Get(int id)
    {
        var book = repository.GetBook(id);
        return Ok(book);
    }
}

This generates the following response:

200 - OK
Content-Type: application/json

Body:
{
    "title": "The Great Gatsby",
    "author": "F. Scott Fitzgerald",
    "yearPublished": 1925
}

400 - Bad Request

To return a 400 – Bad Request response, use the BadRequest() helper method:

[Route("[controller]")]
[ApiController]
public class BooksController : ControllerBase
{
    [HttpPost]
    public IActionResult Save(Book book)
    {
        return BadRequest();
    }
}

This generates:

400 - Bad Request
Content-Type: application/problem+json

Body:
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "Bad Request",
    "status": 400,
    "traceId": "0HMDLM4FOTSV3:00000001"
}

With custom content:

return BadRequest(new { errorCode = 12345 });

This generates:

400 - Bad Request
Content-Type: application/json

Body:
{
    "errorCode": 12345
}

When there’s no specific helper method for a status code, use the StatusCode() helper to return any code. For example, to return a 429 – Too Many Requests response:

using Microsoft.AspNetCore.Http;

[Route("[controller]")]
[ApiController]
public class BooksController : ControllerBase
{
    [HttpPost]
    public IActionResult Save(Book book)
    {
        return StatusCode(StatusCodes.Status429TooManyRequests);
    }
}

This generates:

429 - Too Many Requests
Content-Type: application/problem+json

Body:
{
    "status": 429,
    "traceId": "0HMDLMAQ7DNES:00000001"
}

With custom content:

return StatusCode(StatusCodes.Status429TooManyRequests, "You've reached your limit for today.");

This generates:

429 - Too Many Requests
Content-Type: text/plain

Body:
You've reached your limit for today.

To return a 500 response in ASP.NET Core, the Problem() helper is the simplest and most standardized way. If you need to customize the response, you can modify the parameters or even use StatusCode() to fully control the response body.