> Read the latest version of this page
Edit me on GitHub

pyramid.httpexceptions

HTTP Exception

This module processes Python exceptions that relate to HTTP exceptions by defining a set of exceptions, all subclasses of HTTPException. Each exception, in addition to being a Python exception that can be raised and caught, is also a WSGI application and webob.Response object.

This module defines exceptions according to RFC 2068 [1] : codes with 100-300 are not really errors; 400’s are client errors, and 500’s are server errors. According to the WSGI specification [2] , the application can call start_response more then once only under two conditions: (a) the response has not yet been sent, or (b) if the second and subsequent invocations of start_response have a valid exc_info argument obtained from sys.exc_info(). The WSGI specification then requires the server or gateway to handle the case where content has been sent and then an exception was encountered.

Exception
HTTPException
HTTPOk
  • 200 - HTTPOk
  • 201 - HTTPCreated
  • 202 - HTTPAccepted
  • 203 - HTTPNonAuthoritativeInformation
  • 204 - HTTPNoContent
  • 205 - HTTPResetContent
  • 206 - HTTPPartialContent
HTTPRedirection
  • 300 - HTTPMultipleChoices
  • 301 - HTTPMovedPermanently
  • 302 - HTTPFound
  • 303 - HTTPSeeOther
  • 304 - HTTPNotModified
  • 305 - HTTPUseProxy
  • 306 - Unused (not implemented, obviously)
  • 307 - HTTPTemporaryRedirect
HTTPError
HTTPClientError
  • 400 - HTTPBadRequest
  • 401 - HTTPUnauthorized
  • 402 - HTTPPaymentRequired
  • 403 - HTTPForbidden
  • 404 - HTTPNotFound
  • 405 - HTTPMethodNotAllowed
  • 406 - HTTPNotAcceptable
  • 407 - HTTPProxyAuthenticationRequired
  • 408 - HTTPRequestTimeout
  • 409 - HTTPConflict
  • 410 - HTTPGone
  • 411 - HTTPLengthRequired
  • 412 - HTTPPreconditionFailed
  • 413 - HTTPRequestEntityTooLarge
  • 414 - HTTPRequestURITooLong
  • 415 - HTTPUnsupportedMediaType
  • 416 - HTTPRequestRangeNotSatisfiable
  • 417 - HTTPExpectationFailed
HTTPServerError
  • 500 - HTTPInternalServerError
  • 501 - HTTPNotImplemented
  • 502 - HTTPBadGateway
  • 503 - HTTPServiceUnavailable
  • 504 - HTTPGatewayTimeout
  • 505 - HTTPVersionNotSupported

Subclass usage notes:

The HTTPException class is complicated by 4 factors:

  1. The content given to the exception may either be plain-text or as html-text.
  2. The template may want to have string-substitutions taken from the current environ or values from incoming headers. This is especially troublesome due to case sensitivity.
  3. The final output may either be text/plain or text/html mime-type as requested by the client application.
  4. Each exception has a default explanation, but those who raise exceptions may want to provide additional detail.

Subclass attributes and call parameters are designed to provide an easier path through the complications.

Attributes:

code
the HTTP status code for the exception
title
remainder of the status line (stuff after the code)
explanation
a plain-text explanation of the error message that is not subject to environment or header substitutions; it is accessible in the template via %(explanation)s
detail
a plain-text message customization that is not subject to environment or header substitutions; accessible in the template via %(detail)s
body_template
a content fragment (in HTML) used for environment and header substitution; the default template includes both the explanation and further detail provided in the message

Parameters:

detail
a plain-text override of the default detail
headers
a list of (k,v) header pairs
comment
a plain-text additional information which is usually stripped/hidden for end-users
body_template
a string.Template object containing a content fragment in HTML that frames the explanation and further detail

To override the template (which is HTML content) or the plain-text explanation, one must subclass the given exception; or customize it after it has been created. This particular breakdown of a message into explanation, detail and template allows both the creation of plain-text and html messages for various clients as well as error-free substitution of environment variables and headers.

The subclasses of _HTTPMove (HTTPMultipleChoices, HTTPMovedPermanently, HTTPFound, HTTPSeeOther, HTTPUseProxy and HTTPTemporaryRedirect) are redirections that require a Location field. Reflecting this, these subclasses have two additional keyword arguments: location and add_slash.

Parameters:

location
to set the location immediately
add_slash
set to True to redirect to the same URL as the request, except with a / appended

Relative URLs in the location will be resolved to absolute.

References:

[1]http://www.python.org/peps/pep-0333.html#error-handling
[2]http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5
status_map

A mapping of integer status code to exception class (eg. the integer “401” maps to pyramid.httpexceptions.HTTPUnauthorized).

class HTTPException(message, wsgi_response)
class HTTPOk(detail=None, headers=None, comment=None, body_template=None, **kw)

Base class for the 200’s status code (successful responses)

code: 200, title: OK

class HTTPRedirection(detail=None, headers=None, comment=None, body_template=None, **kw)

base class for 300’s status code (redirections)

This is an abstract base class for 3xx redirection. It indicates that further action needs to be taken by the user agent in order to fulfill the request. It does not necessarly signal an error condition.

class HTTPError(detail=None, headers=None, comment=None, body_template=None, **kw)

base class for status codes in the 400’s and 500’s

This is an exception which indicates that an error has occurred, and that any work in progress should not be committed. These are typically results in the 400’s and 500’s.

class HTTPClientError(detail=None, headers=None, comment=None, body_template=None, **kw)

base class for the 400’s, where the client is in error

This is an error condition in which the client is presumed to be in-error. This is an expected problem, and thus is not considered a bug. A server-side traceback is not warranted. Unless specialized, this is a ‘400 Bad Request’

class HTTPServerError(detail=None, headers=None, comment=None, body_template=None, **kw)

base class for the 500’s, where the server is in-error

This is an error condition in which the server is presumed to be in-error. This is usually unexpected, and thus requires a traceback; ideally, opening a support ticket for the customer. Unless specialized, this is a ‘500 Internal Server Error’

class HTTPCreated(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that request has been fulfilled and resulted in a new resource being created.

code: 201, title: Created

class HTTPAccepted(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the request has been accepted for processing, but the processing has not been completed.

code: 202, title: Accepted

class HTTPNonAuthoritativeInformation(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the returned metainformation in the entity-header is not the definitive set as available from the origin server, but is gathered from a local or a third-party copy.

code: 203, title: Non-Authoritative Information

class HTTPNoContent(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.

code: 204, title: No Content

class HTTPResetContent(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the the server has fulfilled the request and the user agent SHOULD reset the document view which caused the request to be sent.

code: 205, title: Reset Content

class HTTPPartialContent(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the server has fulfilled the partial GET request for the resource.

code: 206, title: Partial Content

class HTTPMultipleChoices(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource corresponds to any one of a set of representations, each with its own specific location, and agent-driven negotiation information is being provided so that the user can select a preferred representation and redirect its request to that location.

code: 300, title: Multiple Choices

class HTTPMovedPermanently(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs.

code: 301, title: Moved Permanently

class HTTPFound(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource resides temporarily under a different URI.

code: 302, title: Found

class HTTPSeeOther(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the response to the request can be found under a different URI and SHOULD be retrieved using a GET method on that resource.

code: 303, title: See Other

class HTTPNotModified(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPRedirection

This indicates that if the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server SHOULD respond with this status code.

code: 304, title: Not Modified

class HTTPUseProxy(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource MUST be accessed through the proxy given by the Location field.

code: 305, title: Use Proxy

class HTTPTemporaryRedirect(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource resides temporarily under a different URI.

code: 307, title: Temporary Redirect

class HTTPBadRequest(detail=None, headers=None, comment=None, body_template=None, **kw)
class HTTPUnauthorized(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the request requires user authentication.

code: 401, title: Unauthorized

class HTTPPaymentRequired(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

code: 402, title: Payment Required

class HTTPForbidden(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server understood the request, but is refusing to fulfill it.

code: 403, title: Forbidden

class HTTPNotFound(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server did not find anything matching the Request-URI.

code: 404, title: Not Found

class HTTPMethodNotAllowed(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the method specified in the Request-Line is not allowed for the resource identified by the Request-URI.

code: 405, title: Method Not Allowed

class HTTPNotAcceptable(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates the resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.

code: 406, title: Not Acceptable

class HTTPProxyAuthenticationRequired(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This is similar to 401, but indicates that the client must first authenticate itself with the proxy.

code: 407, title: Proxy Authentication Required

class HTTPRequestTimeout(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the client did not produce a request within the time that the server was prepared to wait.

code: 408, title: Request Timeout

class HTTPConflict(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the request could not be completed due to a conflict with the current state of the resource.

code: 409, title: Conflict

class HTTPGone(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the requested resource is no longer available at the server and no forwarding address is known.

code: 410, title: Gone

class HTTPLengthRequired(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the the server refuses to accept the request without a defined Content-Length.

code: 411, title: Length Required

class HTTPPreconditionFailed(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the precondition given in one or more of the request-header fields evaluated to false when it was tested on the server.

code: 412, title: Precondition Failed

class HTTPRequestEntityTooLarge(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server is refusing to process a request because the request entity is larger than the server is willing or able to process.

code: 413, title: Request Entity Too Large

class HTTPRequestURITooLong(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server is refusing to service the request because the Request-URI is longer than the server is willing to interpret.

code: 414, title: Request-URI Too Long

class HTTPUnsupportedMediaType(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.

code: 415, title: Unsupported Media Type

class HTTPRequestRangeNotSatisfiable(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

The server SHOULD return a response with this status code if a request included a Range request-header field, and none of the range-specifier values in this field overlap the current extent of the selected resource, and the request did not include an If-Range request-header field.

code: 416, title: Request Range Not Satisfiable

class HTTPExpectationFailed(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indidcates that the expectation given in an Expect request-header field could not be met by this server.

code: 417, title: Expectation Failed

class HTTPInternalServerError(detail=None, headers=None, comment=None, body_template=None, **kw)
class HTTPNotImplemented(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server does not support the functionality required to fulfill the request.

code: 501, title: Not Implemented

class HTTPBadGateway(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.

code: 502, title: Bad Gateway

class HTTPServiceUnavailable(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

code: 503, title: Service Unavailable

class HTTPGatewayTimeout(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.

code: 504, title: Gateway Timeout

class HTTPVersionNotSupported(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server does not support, or refuses to support, the HTTP protocol version that was used in the request message.

code: 505, title: HTTP Version Not Supported

Table Of Contents

Previous topic

pyramid.exceptions

Next topic

pyramid.i18n