Custom Error Responses

Multi-language error messages

Although the Apache HTTP Server provides generic error responses in the event of 4xx or 5xx HTTP status codes, these responses are rather stark, uninformative, and can be intimidating to site users. You may wish to provide custom error responses which are either friendlier, or in some language other than English, or perhaps which are styled more in line with your site layout.

Customized error responses can be defined for any HTTP status code designated as an error condition - that is, any 4xx or 5xx status.

Additionally, a set of values are provided, so that the error document can be customized further based on the values of these variables, using Server Side Includes. Or, you can have error conditions handled by a cgi program, or other dynamic handler (PHP, mod_perl, etc) which makes use of these variables.

ErrorDocument 500 "Sorry, our script crashed. Oh dear"

ErrorDocument 500 /cgi-bin/crash-recover

ErrorDocument 500 http://error.example.com/server_error.html

ErrorDocument 404 /errors/not_found.html

ErrorDocument 401 /subscription/howtosubscribe.html

ErrorDocument <3-digit-code>

where the action will be treated as:

When redirecting to a local URL, additional environment variables are set so that the response can be further customized. They are not sent to external URLs.

To achieve this, when the error redirect is sent, additional environment variables will be set, which will be generated from the headers provided to the original request by prepending 'REDIRECT_' onto the original header name. This provides the error document the context of the original request.

For example, you might receive, in addition to more usual environment variables, the following.

REDIRECTHTTPACCEPT=/, image/gif, image/jpeg, image/png

REDIRECTHTTPUSER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8

REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin

REDIRECTREMOTEADDR=121.345.78.123

REDIRECTREMOTEHOST=client.example.com

REDIRECTSERVERNAME=www.example.edu

REDIRECTSERVERSOFTWARE=Apache/2.2.15

REDIRECT_URL=/cgi-bin/buggy.pl

environment variables are created from the environment variables which existed prior to the redirect. They are renamed with a REDIRECT_

prefix, i.e., HTTPUSERAGENT

target is an ErrorDocumentexternal redirect (anything starting with a scheme name like http:

, even if it refers to the same host as the server).

to some variety of dynamic handler such as a server-side include document, CGI script, or some variety of other handler, you may wish to use the available custom environment variables to customize this response.

" header field in its output in order to ensure the propagation all the way back to the client of the error condition that caused it to be invoked. For instance, a Perl ErrorDocument script might include the following:

... print "Content-type: text/html\n";

printf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"};

If the script is dedicated to handling a particular error condition, such as 404 Not Found

, it can use the specific code and error text instead.

Note that if the response contains Location:

header (in order to issue a client-side redirect), the script must emit an appropriate Status:

header may have no effect.

#Include conf/extra/httpd-multilang-errordoc.conf

line will enable this feature, and provide language-negotiated error messages, based on the language preference set in the client browser.

Additionally, these documents contain various of the REDIRECT_

variables, so that additional information can be provided to the end-user about what happened, and what they can do now.

These documents can be customized to whatever degree you wish to provide more useful information to users about your site, and what they can expect to find there.

must be enabled to use this feature.mod_negotiation

Modules | Directives | FAQ | Glossary | Sitemap

Apache HTTP Server Version 2.4