# `paste.errordocument` – Do internal redirects for error responses

Middleware to display error documents for certain status codes

The middleware in this module can be used to intercept responses with specified status codes and internally forward the request to an appropriate URL where the content can be displayed to the user as an error document.

## Module Contents

class `paste.errordocument.``StatusBasedForward`(app, mapper, global_conf=None, **params)

  Middleware that lets you test a response against a custom mapper object to programatically determine whether to internally forward to another URL and if so, which URL to forward to.

  If you don’t need the full power of this middleware you might choose to use the simpler `forward` middleware instead.

  The arguments are:

  `app`
    The WSGI application or middleware chain.
  `mapper`
    A callable that takes a status code as the first parameter, a message as the second, and accepts optional environ, global_conf and named argments afterwards. It should return a URL to forward to or `None` if the code is not to be intercepted.
  `global_conf`
    Optional default configuration from your config file. If `debug` is set to `true` a message will be written to `wsgi.errors` on each internal forward stating the URL forwarded to.
  `**params`
    Optional, any other configuration and extra arguments you wish to pass which will in turn be passed back to the custom mapper object.

  Here is an example where a `404 File Not Found` status response would be redirected to the URL `/error?code=404&message=File%20Not%20Found`. This could be useful for passing the status code and message into another application to display an error document:

      from paste.errordocument import StatusBasedForward
      from paste.recursive import RecursiveMiddleware
      from urllib import urlencode

      def error_mapper(code, message, environ, global_conf, kw)
          if code in [404, 500]:
              params = urlencode({'message':message, 'code':code})
              url = '/error?'%(params)
              return url
          else:
              return None

      app = RecursiveMiddleware(
          StatusBasedForward(app, mapper=error_mapper),
      )

`paste.errordocument.``make_errordocument`(app, global_conf, **kw)

  Paste Deploy entry point to create a error document wrapper.

  Use like:

      [filter-app:main]
      use = egg:Paste#errordocument
      next = real-app
      500 = /lib/msg/500.html
      404 = /lib/msg/404.html