Custom Error Messages

IIS allows administrators to customize the content that is returned to the client in the case of HTTP errors. Instead of using the HTTP 1.1 errors that are returned to the client by default, Web site administrators can choose to send the client other error messages. These customizable error messages can be in the form of a file or a URL.

If you have an ASP script defined to handle a custom error, the script is invoked as as a URL which passes context. For example, if you have an ASP file called handle404.asp which is defined to handle HTTP 404 errors, when a 404 error occurs when a user tries to access example.htm, then the ASP file will be invoked as if the user had typed http://example.microsoft.com/handle404.asp?404;http://example.microsoft.com/example.htm in the Web browser.

Note   Custom error messages appear as a list in Internet Service Manager and this list is treated as a single property by IIS. For example, when a set of custom errors are configured at the Web site level, all directories under that server inherit the entire list of custom error messages. That is, the two custom error message lists (for server and directory) are not merged.

If you are using static custom error files (HTML files), you should always use the File option. If you plan on developing an application (via ISAPI or ASP) to handle errors, then use URL, but be aware that the error status is handed to the application in the URL parameters and it is the application's responsibility to set the HTTP header status, otherwise the HTTP response status will be HTTP 1.1 200 OK.

The following HTTP error messages can be customized:

Note   Error codes 401 and 403 have sub-codes, which allow for more flexibility in customizing the messages.

"400"; Bad Request
"401"; Unauthorized

1- Logon failed
2- Logon failed due to server configuration
3- Unauthorized due to ACL on resource
4- Authorization failed by filter
5- Authorization failed by ISAPI/CGI application

"403"; Forbidden

1- Execute access forbidden
2- Read access forbidden
3- Write access forbidden
4- SSL required
5- SSL128 required
6- IP address rejected
7- Client certificate required
8- Site access denied
9- Too many users
10 - Invalid configuration
11 - Password Change
12 - Mapper Denied Access

"404"; Not Found
"405"; Method Not Allowed
"406"; Not Acceptable
"407"; Proxy Authentication Required
"412"; Precondition Failed
"414"; Request-URL Too Long
"415"; Unsupported Media Type
"500"; Internal Server Error
"501"; Not Implemented
"502"; Bad Gateway

Adding a Custom Error Message

Custom errors may be in the form of a mapping to a file or a mapping to a URL. Both of these procedures can be achieved by using the Custom Errors property sheet in Internet Service Manager. The following procedure explains how to customize an HTTP error by mapping the error to a URL.

To customize an error message by mapping to a URL:
  1. Create a file that contains your custom error message and place it in a virtual directory.
  2. In Internet Service Manger, select the Web site, virtual directory, directory, or file in which you would like to customize HTTP errors and then click the Properties button.
  3. Select the Custom Errors property sheet.
  4. Select the default HTTP error that you would like to change.
  5. Click the Edit Properties button.
  6. Select URL from the Message Type box
  7. Type the URL which points to your customized error message.
  8. Click OK.

Friendly Custom Error Messages

IIS features its own set of custom errors that provide more informative or "friendly" feedback than the default HTTP 1.1 errors that are returned to client browsers. For example, the HTTP 1.1 404 error message, which by default simply reads "Object Not Found" is expanded to read "The web server cannot find the file/script you asked for. Please check the URL to ensure that the path is correct. Please contact the server's administrator if this problem persists." These friendly custom error messages are set by default in the Default Web Site in Internet Service Manager.

To configure friendly error messages:
  1. In Internet Service Manger, select the Web site, virtual directory, directory, or file in which you would like to customize HTTP errors and then click the Properties button.
  2. Select the Custom Errors property sheet.
  3. Select the default HTTP error that you would like to change.
  4. Click the Edit Properties button.
  5. Select URL from the Message Type box
  6. Type /iisHelp/common/<file name>

where <file name> is the HTML file name of the friendly error message. Friendly error messages are installed by default to the following location: <drive letter>:\WINNT\Help\common. The file names are numbers which correspond to the specific HTTP errors; for example, 400.htm, 401-1.htm, and so on.

© 1997 by Microsoft Corporation. All rights reserved.