How to change the error documents

Using .htaccess file you can easily change the default error pages that are being served by your web server. To use .htaccess to modify your web site error pages your server needs to be configured with AllowOverride FileInfo. Most web hosting servers are configured in such a way so having a custom error page instead of the default ones is possible.

Using a custom error page give you an option to keep your visitors on your site. For example you can have a link to your main page or even your complete site navigation included in the error document. In this even if a user get an error page he/she will be able to navigate to your site main page or some other section of your site. A custom error page always look better than the simple default error pages served by the hosting server.

So for example, let’s start with most common error page. The 404 error page:

ErrorDocument 404 /notfound.html

The line above tells the webserver to use a file named missing.html as error document.
Please note, the leading slash. It tells the browser that this file is located in your web site root folder. In case you miss the slash the webserver will look for a missing.html in the current directory. In case you do not have such a file a default 404 page will be server with a message that an additional error has occurred while trying to find the missing.html file you have defined in your .htaccess file.

If you wish to keep your site structure clean and organized, you can create a folder on your website and keep all custom error pages there. For example you can create a folder named “errors” and place all pages that are going to be used as error handlers there. With a subdirectory your .htaccess file will look like

ErrorDocument 404 /errors/notfound.html

Please, note that the ErrorDocument directive can only be used with local file paths.
This means that you cannot define an error document using full URL, such as:

ErrorDocument 404 http://www.example.com/errors/missing.html

The above line is wrong and will not be woring at all.

Also, when using custom error pages with images, CSS files, javascript files and other linked documents it is always a good idea to use full URL to link to these external files as when an error occurs in a subfolder the relative links will not work. For example if you have:

<img src=”images/badpage.jpg”>

it will only be working well for your website main folder.

To have it working on all levels of your site, it should be either:

<img src=”/images/badpage.jpg”>

or

<img src=”http://www.example.com/images/badpage.jpg”>

Another issue you should have in mind is the strange behaviour of Internet Explorer with error documents that are smaller than 512 bytes. Such error documents will not work properly in Internet explorer. It will replace them with the default IE error page. This issue is known as “Show friendly HTTP error messages” bug in IE. So our advise is always to design your missing pages to be bigger than 512 bytes.

Similar issue can be encountered with error pages that are CGI or PHP scripts (running as CGIs). With some web server configuration a PHP script set as error document may not work properly on IE, unless you send a HTTP 200 response to the browser. (strange issue, but it is happening). Please, note that the issue is only with Internet Explorer. The pages are working fine with FireFox, Netscape and other browsers.

So, now let’s have an example with some more error codes:

ErrorDocument 500 /internal_error.html
ErrorDocument 401 /authorization_required.html
ErrorDocument 403 /forbidden.html

As you can see from the example the ErrorDocument uses a simple syntax:

ErrorDocument <error_code> <path_to_file>

Where <error_code> should be replaced with the HTTP error you should assign a custom error page and the <path_to_file> should be replaced with the path to your own custom error page.

Here it is list of some common HTTP error codes:

400 Bad Request
The server received a request it cannot handle due to bad syntax for example

401 Unauthorized
Such an error will show up in case a user did not supply a proper login credentials when using the .htaccess based user/pass protection

403 Forbidden
The request page is forbidden. Such an error shows up when you have a Deny from directive

404 Not Found
As the error message says the page that you have requested cannot be found on the server.

410 Gone
The requested page have been removed permanently

500 Internal Server Error
The server encountered an error. Usually such error messages show up with CGI scripts. Also you can get such an error message when you have bad syntax in your .htaccess file.

Complete list of HTTP response codes can be found here:
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html