Customizing Web Server Error Messages

IIS generates HTTP error messages when Web server errors occur. These errors typically pertain to bad client requests, authentication problems, or internal server errors. As the administrator, you have complete control over how error messages are sent back to clients. You can configure IIS to send generic HTTP errors or default custom error files, or you can create your own custom error files.

Understanding Status Codes and Error Messages

Status codes and error messages go hand in hand. Every time a user requests a file on a server, the server generates a status code. The status code indicates the status of the user’s request. If the request succeeds, the status code indicates this, and the requested file is returned to the browser. If the request fails, the status code indicates why, and the server generates an appropriate error message based on this error code. This error message is returned to the browser in place of the requested file.

A status code is a three-digit number that might include a numeric suffix. The first digit of the status code indicates the code’s class. The next two digits indicate the error category, and the suffix (if used) indicates the specific error that occurred. For example, the status code 403 indicates an access forbidden problem, and within this access category a number of specific errors can occur: 403.1 indicates that execute access is denied, 403.2 indicates that read access is denied, and 403.3 indicates that write access is denied.

If you examine the Web server logs or receive an error code while trying to troubleshoot a problem, you’ll see status codes. Table 4-2 shows the general classes for status codes. As you can see from the table, the first digit of the status code provides the key indicator as to what has actually happened. Status codes beginning with 1, 2, or 3 are common and generally don’t indicate a problem. Status codes beginning with 4 or 5 indicate an error and a potential problem that you need to resolve.

Table 4-2: General Classes of Status Codes

Code Class	Description
1XX	Continue/protocol change
2XX	Success
3XX	Redirection
4XX	Client error/failure
5XX	Server error

Knowing the general problem is helpful when you’re searching through log files or compiling statistics. When you’re troubleshooting or debugging, you need to know the exact error that occurred. Look up that error code in Table 4-3, which provides a listing of the HTTP 1.1 error codes and a brief description of the error.

Tip

Because of security concerns about providing complete details on errors, the HTTP substatus code is no longer passed to clients (in most instances). Instead, clients should see a general status code, such as 401 or 402. If you’re trying to troubleshoot a problem, you might want to configure access logging so that the substatus codes are recorded in the server logs temporarily. That way you can view the logs to get detailed information on any errors.

Table 4-3: HTTP 1.1 Error Codes and Error Messages

Error Code	Error Text
400	Cannot resolve the request
401.1	Unauthorized: Access is denied due to invalid credentials
401.2	Unauthorized: Access is denied due to server configuration favoring an alternate authentication method
401.3	Unauthorized: Access is denied due to an ACL set on the requested resource
401.4	Unauthorized: Authorization failed by a filter installed on the Web server
401.5	Unauthorized: Authorization failed by an ISAPI/CGI application
401.7	Unauthorized: Access denied by URL authorization policy on the Web server
403.1	Forbidden: Execute access is denied
403.2	Forbidden: Read access is denied
403.3	Forbidden: Write access is denied
403.4	Forbidden: SSL is required to view this resource
403.5	Forbidden: SSL 128 is required to view this resource
403.6	Forbidden: IP address of the client has been rejected
403.7	Forbidden: SSL client certificate is required
403.8	Forbidden: DNS name of the client is rejected
403.9	Forbidden: Too many clients are trying to connect to the Web server
403.10	Forbidden: Web server is configured to deny Execute access
403.11	Forbidden: Password has been changed
403.12	Forbidden: Client certificate is denied access by the server certificate mapper
403.13	Forbidden: Client certificate has been revoked on the Web server
403.14	Forbidden: Directory listing is denied on the Web server
403.15	Forbidden: Client access licenses have exceeded limits on the Web server
403.16	Forbidden: Client certificate is ill-formed or is not trusted by the Web server
403.17	Forbidden: Client certificate has expired or is not yet valid
403.18	Forbidden: Cannot execute requested URL in the current application pool
403.19	Forbidden: Cannot execute CGIs for the client in this application pool
403.20	Forbidden: Passport logon failed
404	File or directory not found
404.1	File or directory not found: Web site not accessible on the requested port
404.2	File or directory not found: Lockdown policy prevents this request
404.3	File or directory not found: MIME map policy prevents this request
405	HTTP verb used to access this page is not allowed
406	Client browser does not accept the MIME type of the requested page
407	Initial proxy authentication required by the Web server
410	File has been removed
412	Precondition set by the client failed when evaluated on the Web server
414	Request URL is too large and therefore unacceptable on the Web server
500	Internal server error
500.11	Server error: Application is shutting down on the Web server
500.12	Server error: Application is busy restarting on the Web server
500.13	Server error: Web server is too busy
500.14	Server error: Invalid application configuration on the server
500.15	Server error: Direct requests for GLOBAL.ASA are not allowed
500.16	Server error: UNC authorization credentials incorrect
500.17	Server error: URL authorization store cannot be found
500.18	Server error: URL authorization store cannot be opened
500.19	Server error: Data for this file is configured improperly in the metabase
500.20	Server error: URL authorization scope cannot be found
500-100	Internal server error: ASP error
501	Header values specify a configuration that is not implemented
502	Web server received an invalid response while acting as a gateway or proxy server

Note

In some cases Internet Explorer might replace custom errors with its own HTTP error message. Typically, this is done when the error message is considered to be too small to be useful to the user. Internet Explorer attempts to determine message usefulness based on message size. When 403, 405, or 410 error messages are smaller than 256 bytes or when 400, 404, 406, 500, 500.12, 500.13, 500.15, or 501 error messages are smaller than 512 bytes, the custom error message sent by IIS is replaced by a message generated by Internet Explorer.

Managing Custom Error Settings

For each of the standard errors, you can specify how the error is handled. Individual files can have different settings from their parent directory and sites, which means that file settings override directory settings and directory settings override site-wide settings. The following error handling options are available:

• Default Sends a standard IIS error message to the client.

• File Sends a customized error file to the client. This option is used with static content.

• URL Sends a message that redirects the client to a specific URL. This option is used with dynamic content.

Custom files supplied in the standard IIS installation handle most HTTP errors. These files are located in the %SystemRoot%\Help\Iishelp\Common directory. You can edit the default error files directly, or you can create your own files. Be sure to use the File error handling option with static content, such as HTML pages, and the URL type handler with dynamic content, such as .asp pages. If you don’t do this, you might get unexpected results.

The following sections examine how you can view and edit error settings.

Real World

When you use an .asp file to handle custom errors, the error code and the original URL are passed to the ASP page as query parameters. You must configure the ASP page to read the parameters from the URL and set the status code appropriately. For example, if Notfound.asp is designed to handle 404 errors and the user accesses a page using the URL http://www.microsoft.com/data.htm/, then the ASP page is invoked using the URL http://www.microsoft.com/NotFound.asp?404; http:// www.microsoft.com/data.htm/, and your ASP page must extract the 404 and http://www.microsoft.com/data.htm/ parameters from the URL.

Viewing Custom Error Settings

You can view custom error settings by following these steps:

1. In the IIS snap-in, right-click the site, directory, or file you want to manage, and then choose Properties.

2. Click the Custom Errors tab. As shown in Figure 4-5, you should now see a list of the standard HTTP errors and how they’re handled. Entries are organized by the following categories:

   • HTTP Error The HTTP status code for the error, which might include a suffix

   • Type The method used to handle the error (default, file, or URL)

   • Contents The error text, file path, or URL path associated with the error

     
     Figure 4-5: The Custom Errors tab shows the error settings for the site, directory, or file you’ve selected for editing.

3. Click OK when you’re finished viewing the error settings.

Editing Custom Error Settings

You can edit custom error settings by completing these steps:

1. In the IIS snap-in, right-click the site, directory, or file you want to manage and then choose Properties.

2. Click the Custom Errors tab. You should now see a list of the standard HTTP errors and how they’re handled.

3. Double-click the entry for the error you want to edit or select the entry and then click Edit. The Edit Custom Error Properties dialog box is displayed, as shown in Figure 4-6.

   
   Figure 4-6: The Edit Custom Error Properties dialog box provides an overview of the error and how it’s handled.

4. Use the Message Type drop-down list to choose the error handling technique. The options available depend on the type of error and generally include the following:

   • Default Uses the default error information shown in the Error Code, Sub Error Code, and Definition fields when returning an error message.

   • File Returns the file specified when the error occurs. Type the complete file path or click Browse to search for the file.

   • URL Returns the URL specified to the client. Type an absolute URL path for resources on other servers or use a relative URL path for resources on the current server.

5. Click OK twice.