How to Setup Custom Umbraco Error Pages per HTTP Status Error Code (e.g: 400, 401, 403, 404, 500, etc.)

In order to create human friendly content editable custom error pages for an Umbraco project, below are the steps that you can follow;

• In your web.config (system.webServer section), add the following setting to tell the site to pass all of the error handling through you application:

       <httpErrors existingResponse="PassThrough" />

• Add the httpErrors - this is an IIS level setting rather than an ASP.NET setting, therefore, this needs to go into the system.webServer section in the web.config:

<system.webServer>

…

    <httpErrors errorMode="Custom" existingResponse="Replace">

      <clear/>

      <error

        statusCode="400"

        path="/error-pages/http-errors/400/"

        responseMode="ExecuteURL"/>

      <error

         statusCode="401"

         path="/error-pages/http-errors/401/"

         responseMode="ExecuteURL"/>

      <error

        statusCode="403"

        path="/error-pages/http-errors/403/"

        responseMode="ExecuteURL"/>

      <error

        statusCode="404"

        path="/error-pages/http-errors/404/"

        responseMode="ExecuteURL"/>

      <error

        statusCode="500"

        path="/error-pages/http-errors/500/"

        responseMode="ExecuteURL"/>

    </httpErrors>

…

</system.webServer>

• Login to umbraco backoffice and create the error pages(if you have different paths than shown above, remember to update your paths - for my case under my home page, I have got an Error Page folder, and under it there is HTTP Errors node and then the error pages)

• Go to your project's umbracoSettings.config file and add the default 404 page node id there too, by adding this; you make sure if any of the error page urls are wrong, then you return your 404 page.

   <content>

   ..

    <errors>

      <!--live & training-->

      <error404>64288</error404>

   ..

   </content>

• Finally test that your custom error pages are returned correctly, you can throw exceptions for this.

     #region Http error code custom page tests

        [Route("BadRequestTest")]

        public ActionResult BadRequest()

        {

            throw new HttpException(400, "Bad request");

        }

        [Route("UnauthorizedTest")]

        public ActionResult Unauthorized()

        {

            // IIS returns 500 for status code 401 - Unauthrorized

            // https://stackoverflow.com/questions/43662305/net-core-returning-500-instead-of-401-when-missing-cookie

            throw new HttpException(401, "Unauthorized");

        }

        [Route("ForbiddenTest")]

        public ActionResult Forbidden()

        {

            throw new HttpException(403, "Forbidden");

        }

        [Route("NotFoundTest")]

        public ActionResult NotFound()

        {

            throw new HttpException(404, "Not found");

        }

        [Route("ServerErrorTest")]

        public ActionResult ServerError()

        {

            throw new HttpException(500, "Server error");

        }

        #endregion Http error code custom page tests

• At this point, it is also good practice to return the correct http status codes for different error pages, for this you can add a new "http status code override" property to the error page's document type in Umbraco and based on the value of this setting, you can return the correct http status code(404, 403, 500 etc). This will hopefully help you and some useful resources can be found here, here and here.

@if (ViewBag.HttpStatusCodeOverrideSelectedValue!=null)

{

        this.Response.StatusCode = Convert.ToInt32(ViewBag.HttpStatusCodeOverrideSelectedValue);

        this.Response.TrySkipIisCustomErrors = true; // disable IIS custom errors

}