d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco This file is generated from xml source: DO NOT EDIT
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<title>Custom Error Responses - Apache HTTP Server Version 2.5</title>
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<script src="/style/scripts/prettify.min.js" type="text/javascript">
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<link href="/images/favicon.ico" rel="shortcut icon" /></head>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<p class="apache">Apache HTTP Server Version 2.5</p>
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="./">Version 2.5</a></div><div id="page-content"><div id="preamble"><h1>Custom Error Responses</h1>
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<p><span>Available Languages: </span><a href="/en/custom-error.html" title="English"> en </a> |
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<a href="/es/custom-error.html" hreflang="es" rel="alternate" title="Espa�ol"> es </a> |
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco<a href="/fr/custom-error.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> |
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<a href="/ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<a href="/ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<a href="/tr/custom-error.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>Although the Apache HTTP Server provides generic error responses
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco in the event of 4xx or 5xx HTTP status codes, these responses are
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco rather stark, uninformative, and can be intimidating to site users.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco You may wish to provide custom error responses which are either
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco friendlier, or in some language other than English, or perhaps which
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco are styled more in line with your site layout.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>Customized error responses can be defined for any HTTP status
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco code designated as an error condition - that is, any 4xx or 5xx
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco <p>Additionally, a set of values are provided, so
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco that the error document can be customized further based on the
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco values of these variables, using <a href="howto/ssi.html">Server
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco Side Includes</a>. Or, you can have error conditions handled by a
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco cgi program, or other dynamic handler (PHP, mod_perl, etc) which
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco makes use of these variables.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#configuration">Configuration</a></li>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<li><img alt="" src="/images/down.gif" /> <a href="#variables">Available Variables</a></li>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<li><img alt="" src="/images/down.gif" /> <a href="#custom">Customizing Error Responses</a></li>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<li><img alt="" src="/images/down.gif" /> <a href="#multi-lang">Multi Language Custom Error Documents</a></li>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<h2><a name="configuration" id="configuration">Configuration</a></h2>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>Custom error documents are configured using the <code class="directive"><a href="/mod/core.html#errordocument">ErrorDocument</a></code> directive,
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco which may be used in global,
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco virtualhost, or directory context. It may be used in .htaccess files
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco if <code class="directive"><a href="/mod/core.html#allowoverride">AllowOverride</a></code> is set to
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco FileInfo.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <pre class="prettyprint lang-config">ErrorDocument 500 "Sorry, our script crashed. Oh dear"<br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoErrorDocument 500 http://error.example.com/server_error.html<br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoErrorDocument 404 /errors/not_found.html <br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoErrorDocument 401 /subscription/how_to_subscribe.html</pre>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>The syntax of the <code>ErrorDocument</code> directive is:</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <pre class="prettyprint lang-config">ErrorDocument <3-digit-code> <action></pre>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <li>A local URL to redirect to (if the action begins with a "/").</li>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <li>An external URL to redirect to (if the action is a valid URL).</li>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <li>Text to be displayed (if none of the above). The text must be
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco wrapped in quotes (") if it consists of more than one word.</li>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>When redirecting to a local URL, additional environment variables
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco are set so that the response can be further customized. They are not sent to
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco external URLs.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<h2><a name="variables" id="variables">Available Variables</a></h2>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>Redirecting to another URL can be useful, but only if some
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco information can be passed which can then be used to explain or log
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco the error condition more clearly.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>To achieve this, when the error redirect is sent, additional
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco environment variables will be set, which will be generated from
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco the headers provided to the original request by prepending
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco 'REDIRECT_' onto the original header name. This provides the error
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco document the context of the original request.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>For example, you might receive, in addition to more usual
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco environment variables, the following.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco REDIRECT_HTTP_ACCEPT=*/*, image/gif, image/jpeg, image/png<br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco REDIRECT_HTTP_USER_AGENT=Mozilla/5.0 Fedora/3.5.8-1.fc12 Firefox/3.5.8<br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco REDIRECT_PATH=.:/bin:/usr/local/bin:/sbin<br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco REDIRECT_QUERY_STRING=<br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco REDIRECT_REMOTE_ADDR=121.345.78.123<br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco REDIRECT_SERVER_PORT=80<br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p><code>REDIRECT_</code> environment variables are created from
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco the environment variables which existed prior to the
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco redirect. They are renamed with a <code>REDIRECT_</code>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco prefix, <em>i.e.</em>, <code>HTTP_USER_AGENT</code> becomes
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p><code>REDIRECT_URL</code>, <code>REDIRECT_STATUS</code>, and
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <code>REDIRECT_QUERY_STRING</code> are guaranteed to be set, and
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco the other headers will be set only if they existed prior to the
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco error condition.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco set if the <code class="directive"><a href="/mod/core.html#errordocument">ErrorDocument</a></code> target is an
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <em>external</em> redirect (anything starting with a
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco scheme name like <code>http:</code>, even if it refers to the same host
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco as the server).</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<h2><a name="custom" id="custom">Customizing Error Responses</a></h2>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>If you point your <code>ErrorDocument</code> to some variety of
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco dynamic handler such as a server-side include document, CGI
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco script, or some variety of other handler, you may wish to use the
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco available custom environment variables to customize this
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco response.</p>
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco <p>If the ErrorDocument specifies a local redirect to a CGI
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco script, the script should include a "<code>Status:</code>"
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco header field in its output in order to ensure the propagation
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco all the way back to the client of the error condition that
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco caused it to be invoked. For instance, a Perl ErrorDocument
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco script might include the following:</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescoprintf "Status: %s Condition Intercepted\n", $ENV{"REDIRECT_STATUS"}; <br />
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>If the script is dedicated to handling a particular error
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco condition, such as <code>404 Not Found</code>, it can
0f77efdcc159eee5682aabf2b9a3c178c467b466Adrián Riesco use the specific code and error text instead.</p>
0f77efdcc159eee5682aabf2b9a3c178c467b466Adrián Riesco <p>Note that if the response contains <code>Location:</code>
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco header (in order to issue a client-side redirect), the script
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco <em>must</em> emit an appropriate <code>Status:</code> header
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco (such as <code>302 Found</code>). Otherwise the
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <code>Location:</code> header may have no effect.</p>
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<h2><a name="multi-lang" id="multi-lang">Multi Language Custom Error Documents</a></h2>
3f8cdebaede9921402318d525b57a9af8f9279d3Adrián Riesco <p>Provided with your installation of the Apache HTTP Server is a
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco directory of custom error documents translated into 16 different
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco languages. There's also a configuration file in the
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <code>conf/extra</code> configuration directory that can be included
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco to enable this feature.</p>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco <p>In your server configuration file, you'll see a line such as:</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <pre class="prettyprint lang-config"> # Multi-language error messages<br />
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco #Include conf/extra/httpd-multilang-errordoc.conf</pre>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <p>Uncommenting this <code>Include</code> line will enable this
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco feature, and provide language-negotiated error messages, based on
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco the language preference set in the client browser.</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <p>Additionally, these documents contain various of the
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <code>REDIRECT_</code> variables, so that additional information can
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco be provided to the end-user about what happened, and what they can
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <p>These documents can be customized to whatever degree you wish to
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco provide more useful information to users about your site, and what
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco they can expect to find there.</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco <p><code class="module"><a href="/mod/mod_include.html">mod_include</a></code> and <code class="module"><a href="/mod/mod_negotiation.html">mod_negotiation</a></code>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco must be enabled to use this feature.</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<p><span>Available Languages: </span><a href="/en/custom-error.html" title="English"> en </a> |
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<a href="/es/custom-error.html" hreflang="es" rel="alternate" title="Espa�ol"> es </a> |
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<a href="/fr/custom-error.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> |
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<a href="/ja/custom-error.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> |
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<a href="/ko/custom-error.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<a href="/tr/custom-error.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<script type="text/javascript"><!--//--><![CDATA[//><!--
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riescovar comments_shortname = 'httpd';
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riescovar comments_identifier = 'http://httpd.apache.org/docs/trunk/custom-error.html';
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco(function(w, d) {
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco d.write('<div id="comments_thread"><\/div>');
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco var s = d.createElement('script');
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco})(window, document);
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<p class="apache">Copyright 2015 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riescoif (typeof(prettyPrint) !== 'undefined') {
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco prettyPrint();