pyramid.httpexceptions

HTTP Exceptions

This module contains Pyramid HTTP exception classes. Each class relates to a single HTTP status code. Each class is a subclass of the HTTPException. Each exception class is also a response object.

Each exception class has a status code according to RFC 2068 or RFC 7538: codes with 100-300 are not really errors; 400s are client errors, and 500s are server errors.

Exception
HTTPException
HTTPSuccessful

  • 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

  • 307 - HTTPTemporaryRedirect

  • 308 - HTTPPermanentRedirect

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

  • 422 - HTTPUnprocessableEntity

  • 423 - HTTPLocked

  • 424 - HTTPFailedDependency

  • 428 - HTTPPreconditionRequired

  • 429 - HTTPTooManyRequests

  • 431 - HTTPRequestHeaderFieldsTooLarge

HTTPServerError

  • 500 - HTTPInternalServerError

  • 501 - HTTPNotImplemented

  • 502 - HTTPBadGateway

  • 503 - HTTPServiceUnavailable

  • 504 - HTTPGatewayTimeout

  • 505 - HTTPVersionNotSupported

  • 507 - HTTPInsufficientStorage

HTTP exceptions are also response objects, thus they accept most of the same parameters that can be passed to a regular Response. Each HTTP exception also has the following 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}

detail

a plain-text message customization that is not subject to environment or header substitutions; accessible in the template via ${detail}

body_template

a String.template-format content fragment used for environment and header substitution; the default template includes both the explanation and further detail provided in the message.

Each HTTP exception accepts the following parameters, any others will be forwarded to its Response superclass:

detail

a plain-text override of the default detail

headers

a list of (k,v) header pairs, or a dict, to be added to the response; use the content_type='application/json' kwarg and other similar kwargs to to change properties of the response supported by the pyramid.response.Response superclass

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

body

a string that will override the body_template and be used as the body of the response.

Substitution of response headers into template values is always performed. Substitution of WSGI environment values is performed if a request is passed to the exception's constructor.

The subclasses of _HTTPMove (HTTPMultipleChoices, HTTPMovedPermanently, HTTPFound, HTTPSeeOther, HTTPUseProxy, HTTPTemporaryRedirect, and :class: ~HTTPPermanentRedirect) are redirections that require a ``Location` field. Reflecting this, these subclasses have one additional keyword argument: location, which indicates the location to which to redirect.

status_map

A mapping of integer status code to HTTP exception class (eg. the integer "401" maps to pyramid.httpexceptions.HTTPUnauthorized). All mapped exception classes are children of pyramid.httpexceptions,

exception_response(status_code, **kw)[source]

Creates an HTTP exception based on a status code. Example:

raise exception_response(404) # raises an HTTPNotFound exception.

The values passed as kw are provided to the exception's constructor.

exception HTTPException(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]
exception HTTPOk(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPSuccessful

Indicates that the request has succeeded.

code: 200, title: OK

exception HTTPRedirection(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

base class for exceptions with status codes in the 300s (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 necessarily signal an error condition.

exception HTTPError(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

base class for exceptions with status codes in the 400s and 500s

This is an exception which indicates that an error has occurred, and that any work in progress should not be committed.

exception HTTPClientError(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

base class for the 400s, 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'

exception HTTPServerError(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

This is an error condition in which the server is presumed to be in-error. Unless specialized, this is a '500 Internal Server Error'.

exception HTTPCreated(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPSuccessful

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

code: 201, title: Created

exception HTTPAccepted(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPSuccessful

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

code: 202, title: Accepted

exception HTTPNonAuthoritativeInformation(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPSuccessful

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

exception HTTPNoContent(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPSuccessful

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

exception HTTPResetContent(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPSuccessful

This indicates that 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

exception HTTPPartialContent(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPSuccessful

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

code: 206, title: Partial Content

exception HTTPMultipleChoices(location='', detail=None, headers=None, comment=None, body_template=None, **kw)[source]

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

exception HTTPMovedPermanently(location='', detail=None, headers=None, comment=None, body_template=None, **kw)[source]

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

exception HTTPFound(location='', detail=None, headers=None, comment=None, body_template=None, **kw)[source]

subclass of _HTTPMove

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

code: 302, title: Found

exception HTTPSeeOther(location='', detail=None, headers=None, comment=None, body_template=None, **kw)[source]

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

exception HTTPNotModified(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPUseProxy(location='', detail=None, headers=None, comment=None, body_template=None, **kw)[source]

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

exception HTTPTemporaryRedirect(location='', detail=None, headers=None, comment=None, body_template=None, **kw)[source]

subclass of _HTTPMove

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

code: 307, title: Temporary Redirect

exception HTTPPermanentRedirect(location='', detail=None, headers=None, comment=None, body_template=None, **kw)[source]

subclass of _HTTPMove

This indicates that the requested resource resides permanently under a different URI and that the request method must not be changed.

code: 308, title: Permanent Redirect

exception HTTPBadRequest(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPClientError

This indicates that the body or headers failed validity checks, preventing the server from being able to continue processing.

code: 400, title: Bad Request

exception HTTPUnauthorized(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPClientError

This indicates that the request requires user authentication.

code: 401, title: Unauthorized

exception HTTPPaymentRequired(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPClientError

code: 402, title: Payment Required

exception HTTPForbidden(detail=None, headers=None, comment=None, body_template=None, result=None, **kw)[source]

subclass of HTTPClientError

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

code: 403, title: Forbidden

Raise this exception within view code to immediately return the forbidden view to the invoking user. Usually this is a basic 403 page, but the forbidden view can be customized as necessary. See Changing the Forbidden View. A Forbidden exception will be the context of a Forbidden View.

This exception's constructor treats two arguments specially. The first argument, detail, should be a string. The value of this string will be used as the message attribute of the exception object. The second special keyword argument, result is usually an instance of pyramid.security.Denied or pyramid.security.ACLDenied each of which indicates a reason for the forbidden error. However, result is also permitted to be just a plain boolean False object or None. The result value will be used as the result attribute of the exception object. It defaults to None.

The Forbidden View can use the attributes of a Forbidden exception as necessary to provide extended information in an error report shown to a user.

exception HTTPNotFound(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPClientError

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

code: 404, title: Not Found

Raise this exception within view code to immediately return the Not Found View to the invoking user. Usually this is a basic 404 page, but the Not Found View can be customized as necessary. See Changing the Not Found View.

This exception's constructor accepts a detail argument (the first argument), which should be a string. The value of this string will be available as the message attribute of this exception, for availability to the Not Found View.

exception HTTPMethodNotAllowed(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPNotAcceptable(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPProxyAuthenticationRequired(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPRequestTimeout(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPConflict(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPGone(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPLengthRequired(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPClientError

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

code: 411, title: Length Required

exception HTTPPreconditionFailed(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPRequestEntityTooLarge(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPRequestURITooLong(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPUnsupportedMediaType(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPRequestRangeNotSatisfiable(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPExpectationFailed(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPClientError

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

code: 417, title: Expectation Failed

exception HTTPUnprocessableEntity(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPClientError

This indicates that the server is unable to process the contained instructions.

May be used to notify the client that their JSON/XML is well formed, but not correct for the current request.

See RFC4918 section 11 for more information.

code: 422, title: Unprocessable Entity

exception HTTPLocked(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPClientError

This indicates that the resource is locked.

code: 423, title: Locked

exception HTTPFailedDependency(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPClientError

This indicates that the method could not be performed because the requested action depended on another action and that action failed.

code: 424, title: Failed Dependency

exception HTTPInternalServerError(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPServerError

This indicates that the server encountered an unexpected condition which prevented it from fulfilling the request.

code: 500, title: Internal Server Error

exception HTTPNotImplemented(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPServerError

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

code: 501, title: Not Implemented

exception HTTPBadGateway(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPServiceUnavailable(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPGatewayTimeout(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPVersionNotSupported(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

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

exception HTTPInsufficientStorage(detail=None, headers=None, comment=None, body_template=None, json_formatter=None, **kw)[source]

subclass of HTTPServerError

This indicates that the server does not have enough space to save the resource.

code: 507, title: Insufficient Storage