Error Handling

Sites may define their own customized error pages. They are registered in the config.xml file:

<config>
  <error-handling>
    <exceptions default="fit://site/public/errors/exception.html" />
    <request-errors default="fit://site/public/errors/error.html" />
    <missing-icons />
  </error-handling>
</config>

Exceptions

Exceptions are thrown, if a fatal error has occured during computation. In this case the request will be terminated immediately.

In contrast to the request errors (see below), no URLs are rewritten. Therefore, depending on the configuration in your domains.xml it’s recommend to use absolute URLs only (e.g. a link to a help or the start/home site).

It’s recommend to inline all resources (e.g. images, css, js) in your exception template to avoid more errors (e.g. request errors) while loading external resources).

Use the error-handling/exceptions setting to define a template which is used for displaying the exceptions.

Placeholders

The follwing placeholders should be used in the template:

  • [[TITLE]]: A short, generic error message that is suitable for title and headings
  • [[EXCEPTION]]: The unique request ID for log file analysis and, if FIT_VERBOSE_EXCEPTIONS are enabled, a detailed error message that may contain file paths other local settings

The replaced strings are encoded in UTF-8. Therefor, your template should set the charset to UTF-8.

Example

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>[[TITLE]]</title>
    <style>
      body {
        margin: 0; padding: 0; font-family: helvetica, arial, sans-serif; font-size: 15pt;
      }
      h1 {
        font-size: 20pt; line-height: 25pt; font-weight: normal;
      }
      a {
        color: #3b7336;
      }
      .head {
        padding: 20pt 30pt; background: linear-gradient(#3b7336, #67a92f); color: white; box-shadow: 0 1px 15px #000;
      }
      .center {
        padding-top: 30pt; text-align: center; line-height: 50pt;
      }
      .foot {
        position: absolute; bottom: 0; width: 100%; box-shadow: 0 -1px 15px #555; background: linear-gradient(#67a92f, #3b7336);
      }
      .foot div {
        color: white; font-size: 12pt; padding: 10pt 15pt;
      }
    </style>
  </head>
  <body>
    <div class="head">
      <a href="http://www.example.com/">
        <img alt="Logo" src="data:image/png;base64,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" />
      </a>
    </div>
    <div class="center">
      <h1>[[TITLE]]</h1>
      <div>[[EXCEPTION]]</div>
      <div>
        <a href="http://www.example.com/">Home</a>
      </div>
    </div>
    <div class="foot">
      <div>Your footer | Links (e.g. to the help site) | Your copyrights</div>
    </div>
  </body>
</html>

Request Errors

Request errors are raised if no content could be loaded. For example if a connection timed out, the request was forbidden or an empty response body was delivered with error status code (e.g. 500). In these cases, the error document is used as the main content. The request/url will contain the FIDJ URI of the error document. Note that HTTP “error” status codes, such as 404 or 500, are handled as valid responses if the body is not empty.

In contrast to the exceptions (see above), the request will not terminate. The content of the error template is taken as the main content in the Flow.

Use the error-handling/request-errors setting to define a template which is used for displaying the request errors.

There are no predefined replacements for this kind of template. However, you may use Text or DOM Filter to use ai-value-of instructions like in the example below.

Example

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Error <ai-value-of select="fit-document('fit://request/content/main/response')/response/@status"/></title>
    <style>
      body {
        margin: 0; padding: 0; font-family: helvetica, arial, sans-serif; font-size: 15pt;
      }
      h1 {
        font-size: 20pt; line-height: 25pt; font-weight: normal;
      }
      a {
        color: #3b7336;
      }
      .head {
        padding: 20pt 30pt; background: linear-gradient(#3b7336, #67a92f); color: white; box-shadow: 0 1px 15px #000;
      }
      .center {
        padding-top: 30pt; text-align: center; line-height: 50pt;
      }
      .foot {
        position: absolute; bottom: 0; width: 100%; box-shadow: 0 -1px 15px #555; background: linear-gradient(#67a92f, #3b7336);
      }
      .foot div {
        color: white; font-size: 12pt; padding: 10pt 15pt;
      }
    </style>
  </head>
  <body>
    <div class="head">
      <a href="/" ai-url-resolver="urlmap">
        <img alt="Logo" src="fit://site/public/logo.png" style="height:40px;" />
      </a>
    </div>
    <div class="center">
      <h1>Error <ai-value-of select="fit-document('fit://request/content/main/response')/response/@status"/></h1>
      <div>
        <a href="/" ai-url-resolver="urlmap">Home</a>
      </div>
    </div>
    <div class="foot">
      <div>Your footer | Links (e.g. to the help site) | Copyrights</div>
    </div>
  </body>
</html>

Missing Icons

Missing icons (favicon.ico, favicon.png, apple-touch-icon.png and apple-touch-icon-precomposed.png) which are automatically requested by some browsers may cause unnecessary work on the server, if they ultimately generate HTML output that must be processed by FIT and sent to the client. This can be prevented by enabling the error-handling option missing-icons. In this case, all requests for the aforementioned URLs with a response status code 3xx (except 304) or 404 return a plain text message “Icon missing” with HTTP status code 404 instead. Thereby, you can reduce the response payload and preserve server resources.

Of course, the best solution would be to create the missing icons and make them available for the clients.