Compartir a través de


Errores HTTP <httpErrors>

Información general

El elemento <httpErrors> le permite configurar mensajes de error personalizados para el sitio o aplicación web. Los mensajes de error personalizados le permiten proporcionar una respuesta sencilla o más informativa al suministrar un archivo, devolver otro recurso o redirigir a una dirección URL cuando los visitantes de su sitio no pueden acceder al contenido que solicitaron. Por ejemplo, quizás desee personalizar cada una de las páginas de mensajes de error del sitio web para que tengan la misma apariencia y comportamiento que el resto del sitio.

El elemento <httpErrors> contiene una colección de elementos <error>, cada uno de los cuales define un mensaje de error que IIS usa para responder a errores HTTP específicos. Puede agregar mensajes de error personalizados a IIS agregando un elemento <error> al elemento <httpErrors> en el archivo Web.config para el sitio, aplicación o dirección URL. Cada elemento <error> usa el atributo responseMode para especificar si IIS sirve contenido estático o dinámico o redirige a una dirección URL independiente en respuesta a un error.

Puede usar el elemento <remove> para quitar un mensaje de error específico de la colección de mensajes de error que su sitio o aplicación hereda de un nivel superior en la jerarquía de configuración de IIS. Además, puede usar el elemento <clear> para quitar todos los mensajes de error HTTP de la colección de mensajes de error HTTP que hereda el sitio o la aplicación.

El elemento <httpErrors> también contiene atributos que configuran IIS 7 para procesar solicitudes que provocan errores. El atributo existingResponse define lo que hace IIS 7 a una respuesta existente cuando el servidor devuelve un código de estado de error HTTP. El atributo defaultPath define la ruta de acceso a una página de error del cliente si elige especificar Archivo para el atributo responseMode en un elemento <error>.

El atributo detailedMoreInformationLink especifica un vínculo a más información sobre un error determinado.

El elemento <httpErrors> también puede contener un atributo errorMode que puede usar para controlar el nivel de detalle que IIS devuelve a un explorador cuando se produce un error HTTP. Puede establecer el atributo errorMode en DetailedLocalOnly, que es la configuración predeterminada, o bien puede establecerlo en Custom o Detailed. Si especifica DetailedLocalOnly o, si no especifica un valor errorMode, IIS devuelve información detallada del error solo al explorador del servidor local y un mensaje de error personalizado a un explorador de un equipo externo. Si establece el valor errorMode en Custom, IIS devuelve solo mensajes de error personalizados a todos los exploradores solicitantes. Si establece el valor errorMode en Detailed, IIS devuelve información detallada del error a todos los exploradores solicitantes. El valor DetailedLocalOnly predeterminado le permite solucionar errores HTTP en el servidor local, al tiempo que no se expone información confidencial a exploradores externos.

De forma predeterminada, IIS proporciona mensajes de error definidos en los archivos almacenados en la carpeta %SystemRoot%\Help\IisHelp\Common. Puede crear un mensaje de error personalizado para los usuarios y configurar IIS para que devuelva esta página cada vez que encuentre un error HTTP específico en el sitio.

Compatibilidad

Versión Notas
IIS 10.0 El elemento <httpErrors> no se modificó en IIS 10.0.
IIS 8.5 El elemento <httpErrors> no se modificó en IIS 8.5.
IIS 8.0 El elemento <httpErrors> no se modificó en IIS 8.0.
IIS 7.5 El atributo allowAbsolutePathsWhenDelegated se agregó al elemento <httpErrors> en IIS 7.5.
IIS 7.0 El elemento <httpErrors> se introdujo en IIS 7.0.
IIS 6,0 El elemento <httpErrors> reemplaza a la propiedad HttpErrors de IIS 6.0 del objeto metabase IIsWebService.

Configuración

El elemento <httpErrors> se incluye en la instalación predeterminada de IIS 7.

Procedimientos

Adición de una página de error personalizada

  1. Abra el Administrador de Internet Information Services (IIS):

    • Si usa Windows Server 2012 o Windows Server 2012 R2:

      • En la barra de tareas, haga clic en Administrador del servidor, en Herramientas y, a continuación, en Administrador de Internet Information Services (IIS).
    • Si usa Windows 8 o Windows 8.1:

      • Mantenga presionada la tecla Windows, presione la letra X y haga clic en Panel de control.
      • En Panel de control, haga clic en Herramientas administrativas y, a continuación, haga doble clic en Administrador de Internet Information Services (IIS).
    • Si usa Windows Server 2008 o Windows Server 2008 R2:

      • En la barra de tareas, haga clic en Inicio, seleccione Herramientas administrativas y, a continuación, haga clic en Administrador de Internet Information Services (IIS).
    • Si usa Windows Vista o Windows 7:

      • En la barra de tareas, haga clic en Inicio y, luego, haga clic en Panel de control.
      • Haga doble clic en Herramientas administrativas y, a continuación, haga doble clic en Administrador de Internet Information Services (IIS).
  2. En el panel Conexiones, expanda el nombre del servidor, expanda Sitios y, a continuación, vaya al sitio o aplicación web en los que desea configurar páginas de error personalizadas.

  3. En el panel Inicio, haga doble clic en Páginas de error.
    Screenshot that shows the Error Pages double-clicked.

  4. En el panel Acciones, haga clic en Agregar....

  5. En el cuadro de diálogo Agregar página de error personalizada, en Código de estado, escriba el número del código de estado HTTP para el que desea crear un mensaje de error personalizado.
    Screenshot that shows the Add Custom Error Page.

  6. En la sección Acción de respuesta, realice una de las acciones siguientes:

    • Seleccione Insertar contenido del archivo estático en la respuesta de error para servir contenido estático, por ejemplo, un archivo .html para el error personalizado.
    • Seleccione Ejecutar una dirección URL en este sitio para servir contenido dinámico, por ejemplo, un archivo .asp para el error personalizado.
    • Seleccione Responder con un redireccionamiento 302 para redirigir los exploradores cliente a una dirección URL diferente que contenga el archivo de error personalizado.
  7. En el cuadro de texto Ruta de archivo, escriba la ruta de acceso de la página de error personalizada si eligió Insertar contenido del archivo estático en la respuesta de error o la dirección URL de la página de error personalizada si usa Ejecutar una dirección URL en este sitio o Responder con un redireccionamiento 302 y, a continuación, haga clic en Aceptar.

    Nota:

    Si selecciona Ejecutar una dirección URL en este sitio, la ruta de acceso debe ser una ruta de acceso relativa. Si selecciona Responder con un redireccionamiento 302, la dirección URL debe ser una dirección URL absoluta.

Configuración

Puede configurar el elemento <httpErrors> a nivel de servidor en el archivo ApplicationHost.config y a nivel de sitio y aplicación en el archivo Web.config adecuado.

Atributos

Atributo Descripción
allowAbsolutePathsWhenDelegated Atributo Boolean opcional.

Cuando se establece en true, se permiten rutas de acceso absolutas para páginas de error personalizadas cuando se delega la sección <httpErrors>. Cuando se establece en false, solo se permiten rutas de acceso relativas a la raíz del sitio.

El valor predeterminado es false.
defaultPath Atributo de cadena opcional.

Especifica la ruta de acceso predeterminada de la página de error personalizada. El tipo de ruta de acceso viene determinado por el atributo defaultResponseMode. Si elige Archivo, se devuelve la ruta del archivo. Si elige el tipo de ruta de acceso ExecuteURL o Redirect, se devuelve la dirección URL de la página de error personalizada.
defaultResponseMode Atributo enum opcional.

Especifica cómo se devuelve el contenido de errores personalizados.

El atributo defaultResponseMode puede tener uno de los siguientes valores posibles; el valor predeterminado es File.
Valor Descripción
File Sirve contenido estático, por ejemplo, un archivo .html para el error personalizado. Si responseMode se establece en Archivo, el valor de la ruta de acceso debe ser una ruta de archivo.

El valor numérico es 0.
ExecuteURL Sirve contenido dinámico, por ejemplo, un archivo .asp para el error personalizado. Si responseMode se establece en ExecuteURL, el valor de la ruta de acceso debe ser una dirección URL relativa del servidor.

El valor numérico es 1.
Redirect Redirige los exploradores cliente a otra dirección URL que contiene el archivo de error personalizado. Si responseMode se establece en Redirect, el valor de la ruta de acceso debe ser una dirección URL absoluta.

El valor numérico es 2.
detailedMoreInformationLink Atributo de cadena opcional.

Especifica un vínculo, que se muestra en la parte inferior de la página, a una página con información más detallada sobre un error determinado. Puede usar esta propiedad para dirigir a los usuarios finales a una ubicación personalizada para obtener información del error. El estado, el subestado, HRESULT y el identificador de mensaje se envían como parte de la cadena de consulta.

El valor predeterminado es https://go.microsoft.com/fwlink/?LinkID=62293.
errorMode Atributo enum opcional.

Especifica si los errores HTTP están habilitados.

El atributo errorMode puede tener uno de los siguientes valores; el valor predeterminado es DetailedLocalOnly.
Valor Descripción
DetailedLocalOnly Devuelve información detallada del error si la solicitud procede del equipo local, y devuelve un mensaje de error personalizado si la solicitud procede de un equipo externo.

El valor numérico es 0.
Custom Reemplaza el error que genera el módulo o el servidor por una página personalizada que especifique. Este modo es útil para proporcionar mensajes de error más sencillos a los usuarios finales.

Nota: Esta configuración desactiva los errores detallados, incluso para las solicitudes locales.

El valor numérico es 1.
Detailed Devuelve información detallada del error al cliente. Este modo es útil para probar y depurar sitios y aplicaciones web.

El valor numérico es 2.
existingResponse Atributo enum opcional.

Especifica lo que ocurre con una respuesta existente cuando el código de estado HTTP es un error, es decir, códigos de respuesta >= 400.

El atributo existingResponse puede tener uno de los siguientes valores; el valor predeterminado es Auto.
Valor Descripción
Auto Deja la respuesta intacta solo si se establece la marca SetStatus.

El valor numérico es 0.
Replace Reemplaza la respuesta existente incluso si se establece la marca SetStatus.

El valor numérico es 1.
PassThrough Deja la respuesta intacta si ya hay una respuesta.

El valor numérico es 2.

Elementos secundarios

Elemento Descripción
error Elemento opcional.

Agrega un error HTTP a la colección de errores HTTP.
remove Elemento opcional.

Quita una referencia a un error HTTP de la colección de errores HTTP.
clear Elemento opcional.

Quita todas las referencias a errores HTTP de la colección de errores HTTP.

Ejemplo de configuración

En el ejemplo de configuración siguiente, cuando se incluye en el archivo Web.config para un sitio o aplicación web, se usa el atributo errorMode para permitir que solo aparezcan mensajes de error detallados en el equipo local. También se usa el atributo defaultResponseMode para establecer el modo de respuesta para el sitio o la aplicación. A continuación, en el ejemplo se quita el mensaje de error heredado para el código de estado 500. Luego, se establece el atributo prefixLanguageFilePath en el directorio donde IIS debe buscar una nueva página de error personalizada y establece el atributo path en 500.htm, el archivo que contiene el mensaje de error personalizado.

<configuration>
   <system.webServer>
      <httpErrors errorMode="DetailedLocalOnly" defaultResponseMode="File" >
         <remove statusCode="500" />
         <error statusCode="500"
            prefixLanguageFilePath="C:\Contoso\Content\errors"
            path="500.htm" />
       </httpErrors>
   </system.webServer>
</configuration>

Código de ejemplo

En los ejemplos siguientes se agrega un nuevo archivo para todos los errores de código de estado 404 con un subestado de 5, que IIS devuelve para errores en "Secuencia de direcciones URL denegadas". En estos ejemplos, la ruta de acceso del prefijo se establece en "%SystemDrive%\inetpub\custerr" y el nombre de archivo se especifica como "404.5.htm".

AppCmd.exe

appcmd.exe set config -section:system.webServer/httpErrors /+"[statusCode='404',subStatusCode='5',prefixLanguageFilePath='%SystemDrive%\inetpub\custerr',path='404.5.htm']" /commit:apphost

Nota:

Debe asegurarse de establecer el parámetro de confirmación en apphost cuando use AppCmd.exe para configurar estas opciones. Esto confirma los valores de configuración en la sección de ubicación adecuada del archivo ApplicationHost.config.

C#

using System;
using System.Text;
using Microsoft.Web.Administration;

internal static class Sample
{
   private static void Main()
   {
      using (ServerManager serverManager = new ServerManager())
      {
         Configuration config = serverManager.GetApplicationHostConfiguration();
         ConfigurationSection httpErrorsSection = config.GetSection("system.webServer/httpErrors");
         ConfigurationElementCollection httpErrorsCollection = httpErrorsSection.GetCollection();

         ConfigurationElement errorElement = httpErrorsCollection.CreateElement("error");
         errorElement["statusCode"] = 404;
         errorElement["subStatusCode"] = 5;
         errorElement["prefixLanguageFilePath"] = @"%SystemDrive%\inetpub\custerr";
         errorElement["path"] = @"404.5.htm";
         httpErrorsCollection.Add(errorElement);

         serverManager.CommitChanges();
      }
   }
}

VB.NET

Imports System
Imports System.Text
Imports Microsoft.Web.Administration

Module Sample
   Sub Main()
      Dim serverManager As ServerManager = New ServerManager
      Dim config As Configuration = serverManager.GetApplicationHostConfiguration
      Dim httpErrorsSection As ConfigurationSection = config.GetSection("system.webServer/httpErrors")
      Dim httpErrorsCollection As ConfigurationElementCollection = httpErrorsSection.GetCollection

      Dim errorElement As ConfigurationElement = httpErrorsCollection.CreateElement("error")
      errorElement("statusCode") = 404
      errorElement("subStatusCode") = 5
      errorElement("prefixLanguageFilePath") = "%SystemDrive%\inetpub\custerr"
      errorElement("path") = "404.5.htm"
      httpErrorsCollection.Add(errorElement)

      serverManager.CommitChanges()
   End Sub
End Module

JavaScript

var adminManager = new ActiveXObject('Microsoft.ApplicationHost.WritableAdminManager');
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST";
var httpErrorsSection = adminManager.GetAdminSection("system.webServer/httpErrors", "MACHINE/WEBROOT/APPHOST");
var httpErrorsCollection = httpErrorsSection.Collection;

var errorElement = httpErrorsCollection.CreateNewElement("error");
errorElement.Properties.Item("statusCode").Value = 404;
errorElement.Properties.Item("subStatusCode").Value = 5;
errorElement.Properties.Item("prefixLanguageFilePath").Value = "%SystemDrive%\\inetpub\\custerr";
errorElement.Properties.Item("path").Value = "404.5.htm";
httpErrorsCollection.AddElement(errorElement);

adminManager.CommitChanges();

VBScript

Set adminManager = createObject("Microsoft.ApplicationHost.WritableAdminManager")
adminManager.CommitPath = "MACHINE/WEBROOT/APPHOST"
Set httpErrorsSection = adminManager.GetAdminSection("system.webServer/httpErrors", "MACHINE/WEBROOT/APPHOST")
Set httpErrorsCollection = httpErrorsSection.Collection

Set errorElement = httpErrorsCollection.CreateNewElement("error")
errorElement.Properties.Item("statusCode").Value = 404
errorElement.Properties.Item("subStatusCode").Value = 5
errorElement.Properties.Item("prefixLanguageFilePath").Value = "%SystemDrive%\inetpub\custerr"
errorElement.Properties.Item("path").Value = "404.5.htm"
httpErrorsCollection.AddElement errorElement

adminManager.CommitChanges()