Spring Boot - Mapping HTTP Response Status Codes to Static HTML Pages

[Last Updated: Feb 25, 2018]

This example shows how to map static html error pages to HTTP Response Status codes. We can add our error pages at any of the static location as described here.


The Controller

public class MyController {

  public void handleRequest() {
      throw new RuntimeException("test exception");

  public void handleAppInfoRequest() throws NotYetImplemented {
      throw new NotYetImplemented("The request page is not yet implemented");

Specifying Status code on Custom Exception

public class NotYetImplemented extends Exception {
  public NotYetImplemented(String message) {

The NOT_IMPLEMENTED will return the response status code of 501.

Mappings of Status Codes to HTML Pages


<h1>My 5xx Error Page</h1>
<div id="locationDiv"></div>
     document.getElementById("locationDiv").innerHTML = "Location: " + window.location.href;

Above page will map to all status codes of pattern 5xx e.g. 500, 501 etc.

Let's also add a 404.html (not found) error page:


<h1>My 404 Error Page</h1>
<div id="locationDiv"></div>
     document.getElementById("locationDiv").innerHTML = "Location: " + window.location.href;

Note that we cannot map a static global page error.html to other status codes and exceptions (as we did in the last example by adding error.jsp).

Main class

public class SpringBootMain extends SpringBootServletInitializer {

  protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
      return builder.sources(SpringBootMain.class);

  public static void main(String[] args) {;


To try examples, run spring-boot maven plugin (configured in pom.xml of example project below):

mvn spring-boot:run

We can also run the main method from our IDE.

Accessing 'http:/localhost:8080/app-info' where our handler method (handleAppInfoRequest()) throws the custom exception will map to 501 status code:

Accessing unmapped URL, say 'http:/localhost:8080/other', will map to our 404.html page:

Accessing 'http:/localhost:8080/', where we our handler method (handleRequest()) throws RuntimeException will return the response code 500 (Internal server error) :

Example Project

Dependencies and Technologies Used:

  • Spring Boot 1.5.10.RELEASE
    Corresponding Spring Version 4.3.14.RELEASE
  • spring-boot-starter-web : Starter for building web, including RESTful, applications using Spring MVC. Uses Tomcat as the default embedded container.
  • JDK 1.8
  • Maven 3.3.9

Boot Custom Static Pages Status Code Mapping Example Select All Download
  • static-pages-status-code-mapping
    • src
      • main
        • java
          • com
            • logicbig
              • example
        • resources
          • static
            • error
              • 5xx.html

    See Also