.. currentmodule:: aiohttp.web

.. _aiohttp-web-exceptions:

Web Server Exceptions

Overview

:mod:aiohttp.web defines a set of exceptions for every HTTP status code.

Each exception is a subclass of :exc:HTTPException and relates to a single HTTP status code::

async def handler(request):
    raise aiohttp.web.HTTPFound('/redirect')

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

HTTP Exception hierarchy chart::

Exception HTTPException HTTPSuccessful * 200 - HTTPOk * 201 - HTTPCreated * 202 - HTTPAccepted * 203 - HTTPNonAuthoritativeInformation * 204 - HTTPNoContent * 205 - HTTPResetContent * 206 - HTTPPartialContent HTTPRedirection * 304 - HTTPNotModified HTTPMove * 300 - HTTPMultipleChoices * 301 - HTTPMovedPermanently * 302 - HTTPFound * 303 - HTTPSeeOther * 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 * 421 - HTTPMisdirectedRequest * 422 - HTTPUnprocessableEntity * 424 - HTTPFailedDependency * 426 - HTTPUpgradeRequired * 428 - HTTPPreconditionRequired * 429 - HTTPTooManyRequests * 431 - HTTPRequestHeaderFieldsTooLarge * 451 - HTTPUnavailableForLegalReasons HTTPServerError * 500 - HTTPInternalServerError * 501 - HTTPNotImplemented * 502 - HTTPBadGateway * 503 - HTTPServiceUnavailable * 504 - HTTPGatewayTimeout * 505 - HTTPVersionNotSupported * 506 - HTTPVariantAlsoNegotiates * 507 - HTTPInsufficientStorage * 510 - HTTPNotExtended * 511 - HTTPNetworkAuthenticationRequired

All HTTP exceptions have the same constructor signature::

HTTPNotFound(*, headers=None, reason=None,
             text=None, content_type=None)

If not directly specified, headers will be added to the default response headers.

Classes :exc:HTTPMultipleChoices, :exc:HTTPMovedPermanently, :exc:HTTPFound, :exc:HTTPSeeOther, :exc:HTTPUseProxy, :exc:HTTPTemporaryRedirect have the following constructor signature::

HTTPFound(location, *,headers=None, reason=None,
          text=None, content_type=None)

where location is value for Location HTTP header.

:exc:HTTPMethodNotAllowed is constructed by providing the incoming unsupported method and list of allowed methods::

HTTPMethodNotAllowed(method, allowed_methods, *,
                     headers=None, reason=None,
                     text=None, content_type=None)

:exc:HTTPUnavailableForLegalReasons should be constructed with a link to yourself (as the entity implementing the blockage), and an explanation for the block included in text.::

HTTPUnavailableForLegalReasons(link, *,
                               headers=None, reason=None,
                               text=None, content_type=None)

Base HTTP Exception

.. exception:: HTTPException(*, headers=None, reason=None, text=None,
content_type=None) :canonical: aiohttp.web_exceptions.HTTPException

The base class for HTTP server exceptions. Inherited from :exc:Exception.

:param headers: HTTP headers (:class:~collections.abc.Mapping)

:param str reason: an optional custom HTTP reason. aiohttp uses default reason string if not specified.

:param str text: an optional text used in response body. If not specified default text is constructed from status code and reason, e.g. "404: Not Found".

:param str content_type: an optional Content-Type, "text/plain" by default.

.. attribute:: status

  HTTP status code for the exception, :class:`int`

.. attribute:: reason

  HTTP status reason for the exception, :class:`str`

.. attribute:: text

  HTTP status reason for the exception, :class:`str` or ``None``
  for HTTP exceptions without body, e.g. "204 No Content"

.. attribute:: headers

  HTTP headers for the exception, :class:`multidict.CIMultiDict`

.. attribute:: cookies

  An instance of :class:`http.cookies.SimpleCookie` for *outgoing* cookies.

  .. versionadded:: 4.0

.. method:: set_cookie(name, value, *, path='/', expires=None,
domain=None, max_age=None,
secure=None, httponly=None, version=None,
samesite=None)

  Convenient way for setting :attr:`cookies`, allows to specify
  some additional properties like *max_age* in a single call.

  .. versionadded:: 4.0

  :param str name: cookie name

  :param str value: cookie value (will be converted to
                    :class:`str` if value has another type).

  :param expires: expiration date (optional)

  :param str domain: cookie domain (optional)

  :param int max_age: defines the lifetime of the cookie, in
                      seconds.  The delta-seconds value is a
                      decimal non- negative integer.  After
                      delta-seconds seconds elapse, the client
                      should discard the cookie.  A value of zero
                      means the cookie should be discarded
                      immediately.  (optional)

  :param str path: specifies the subset of URLs to
                   which this cookie applies. (optional, ``'/'`` by default)

  :param bool secure: attribute (with no value) directs
                      the user agent to use only (unspecified)
                      secure means to contact the origin server
                      whenever it sends back this cookie.
                      The user agent (possibly under the user's
                      control) may determine what level of
                      security it considers appropriate for
                      "secure" cookies.  The *secure* should be
                      considered security advice from the server
                      to the user agent, indicating that it is in
                      the session's interest to protect the cookie
                      contents. (optional)

  :param bool httponly: ``True`` if the cookie HTTP only (optional)

  :param int version: a decimal integer, identifies to which
                      version of the state management
                      specification the cookie
                      conforms. (Optional, *version=1* by default)

  :param str samesite: Asserts that a cookie must not be sent with
     cross-origin requests, providing some protection
     against cross-site request forgery attacks.
     Generally the value should be one of: ``None``,
     ``Lax`` or ``Strict``. (optional)

  .. warning::

     In HTTP version 1.1, ``expires`` was deprecated and replaced with
     the easier-to-use ``max-age``, but Internet Explorer (IE6, IE7,
     and IE8) **does not** support ``max-age``.

.. method:: del_cookie(name, *, path='/', domain=None)

  Deletes cookie.

  .. versionadded:: 4.0

  :param str name: cookie name

  :param str domain: optional cookie domain

  :param str path: optional cookie path, ``'/'`` by default

Successful Exceptions

HTTP exceptions for status code in range 200-299. They are not errors but special classes reflected in exceptions hierarchy. E.g. raise web.HTTPNoContent may look strange a little but the construction is absolutely legal.

.. exception:: HTTPSuccessful :canonical: aiohttp.web_exceptions.HTTPSuccessful

A base class for the category, a subclass of :exc:HTTPException.

.. exception:: HTTPOk :canonical: aiohttp.web_exceptions.HTTPOk

An exception for 200 OK, a subclass of :exc:HTTPSuccessful.

.. exception:: HTTPCreated :canonical: aiohttp.web_exceptions.HTTPCreated

An exception for 201 Created, a subclass of :exc:HTTPSuccessful.

.. exception:: HTTPAccepted :canonical: aiohttp.web_exceptions.HTTPAccepted

An exception for 202 Accepted, a subclass of :exc:HTTPSuccessful.

.. exception:: HTTPNonAuthoritativeInformation :canonical: aiohttp.web_exceptions.HTTPNonAuthoritativeInformation

An exception for 203 Non-Authoritative Information, a subclass of :exc:HTTPSuccessful.

.. exception:: HTTPNoContent :canonical: aiohttp.web_exceptions.HTTPNoContent

An exception for 204 No Content, a subclass of :exc:HTTPSuccessful.

Has no HTTP body.

.. exception:: HTTPResetContent :canonical: aiohttp.web_exceptions.HTTPResetContent

An exception for 205 Reset Content, a subclass of :exc:HTTPSuccessful.

Has no HTTP body.

.. exception:: HTTPPartialContent :canonical: aiohttp.web_exceptions.HTTPPartialContent

An exception for 206 Partial Content, a subclass of :exc:HTTPSuccessful.

Redirections

HTTP exceptions for status code in range 300-399, e.g. raise web.HTTPMovedPermanently(location='/new/path').

.. exception:: HTTPRedirection :canonical: aiohttp.web_exceptions.HTTPRedirection

A base class for the category, a subclass of :exc:HTTPException.

.. exception:: HTTPMove(location, *, headers=None, reason=None, text=None,
content_type=None) :canonical: aiohttp.web_exceptions.HTTPMove

A base class for redirections with implied Location header, all redirections except :exc:HTTPNotModified.

:param location: a :class:yarl.URL or :class:str used for Location HTTP header.

For other arguments see :exc:HTTPException constructor.

.. attribute:: location

  A *Location* HTTP header value, :class:`yarl.URL`.

.. exception:: HTTPMultipleChoices :canonical: aiohttp.web_exceptions.HTTPMultipleChoices

An exception for 300 Multiple Choices, a subclass of :exc:HTTPMove.

.. exception:: HTTPMovedPermanently :canonical: aiohttp.web_exceptions.HTTPMovedPermanently

An exception for 301 Moved Permanently, a subclass of :exc:HTTPMove.

.. exception:: HTTPFound :canonical: aiohttp.web_exceptions.HTTPFound

An exception for 302 Found, a subclass of :exc:HTTPMove.

.. exception:: HTTPSeeOther :canonical: aiohttp.web_exceptions.HTTPSeeOther

An exception for 303 See Other, a subclass of :exc:HTTPMove.

.. exception:: HTTPNotModified :canonical: aiohttp.web_exceptions.HTTPNotModified

An exception for 304 Not Modified, a subclass of :exc:HTTPRedirection.

Has no HTTP body.

.. exception:: HTTPUseProxy :canonical: aiohttp.web_exceptions.HTTPUseProxy

An exception for 305 Use Proxy, a subclass of :exc:HTTPMove.

.. exception:: HTTPTemporaryRedirect :canonical: aiohttp.web_exceptions.HTTPTemporaryRedirect

An exception for 307 Temporary Redirect, a subclass of :exc:HTTPMove.

.. exception:: HTTPPermanentRedirect :canonical: aiohttp.web_exceptions.HTTPPermanentRedirect

An exception for 308 Permanent Redirect, a subclass of :exc:HTTPMove.

Client Errors

HTTP exceptions for status code in range 400-499, e.g. raise web.HTTPNotFound().

.. exception:: HTTPClientError :canonical: aiohttp.web_exceptions.HTTPClientError

A base class for the category, a subclass of :exc:HTTPException.

.. exception:: HTTPBadRequest :canonical: aiohttp.web_exceptions.HTTPBadRequest

An exception for 400 Bad Request, a subclass of :exc:HTTPClientError.

.. exception:: HTTPUnauthorized :canonical: aiohttp.web_exceptions.HTTPUnauthorized

An exception for 401 Unauthorized, a subclass of :exc:HTTPClientError.

.. exception:: HTTPPaymentRequired :canonical: aiohttp.web_exceptions.HTTPPaymentRequired

An exception for 402 Payment Required, a subclass of :exc:HTTPClientError.

.. exception:: HTTPForbidden :canonical: aiohttp.web_exceptions.HTTPForbidden

An exception for 403 Forbidden, a subclass of :exc:HTTPClientError.

.. exception:: HTTPNotFound :canonical: aiohttp.web_exceptions.HTTPNotFound

An exception for 404 Not Found, a subclass of :exc:HTTPClientError.

.. exception:: HTTPMethodNotAllowed(method, allowed_methods, *,
headers=None, reason=None, text=None,
content_type=None) :canonical: aiohttp.web_exceptions.HTTPMethodNotAllowed

An exception for 405 Method Not Allowed, a subclass of :exc:HTTPClientError.

:param str method: requested but not allowed HTTP method.

:param allowed_methods: an iterable of allowed HTTP methods (:class:str), Allow HTTP header is constructed from the sequence separated by comma.

For other arguments see :exc:HTTPException constructor.

.. attribute:: allowed_methods

  A set of allowed HTTP methods.

.. attribute:: method

  Requested but not allowed HTTP method.

.. exception:: HTTPNotAcceptable :canonical: aiohttp.web_exceptions.HTTPNotAcceptable

An exception for 406 Not Acceptable, a subclass of :exc:HTTPClientError.

.. exception:: HTTPProxyAuthenticationRequired :canonical: aiohttp.web_exceptions.HTTPProxyAuthenticationRequired

An exception for 407 Proxy Authentication Required, a subclass of :exc:HTTPClientError.

.. exception:: HTTPRequestTimeout :canonical: aiohttp.web_exceptions.HTTPRequestTimeout

An exception for 408 Request Timeout, a subclass of :exc:HTTPClientError.

.. exception:: HTTPConflict :canonical: aiohttp.web_exceptions.HTTPConflict

An exception for 409 Conflict, a subclass of :exc:HTTPClientError.

.. exception:: HTTPGone :canonical: aiohttp.web_exceptions.HTTPGone

An exception for 410 Gone, a subclass of :exc:HTTPClientError.

.. exception:: HTTPLengthRequired :canonical: aiohttp.web_exceptions.HTTPLengthRequired

An exception for 411 Length Required, a subclass of :exc:HTTPClientError.

.. exception:: HTTPPreconditionFailed :canonical: aiohttp.web_exceptions.HTTPPreconditionFailed

An exception for 412 Precondition Failed, a subclass of :exc:HTTPClientError.

.. exception:: HTTPRequestEntityTooLarge(max_size, actual_size, **kwargs) :canonical: aiohttp.web_exceptions.HTTPRequestEntityTooLarge

An exception for 413 Entity Too Large, a subclass of :exc:HTTPClientError.

:param int max_size: Maximum allowed request body size

:param int actual_size: Actual received size

For other acceptable parameters see :exc:HTTPException constructor.

.. exception:: HTTPRequestURITooLong :canonical: aiohttp.web_exceptions.HTTPRequestURITooLong

An exception for 414 URI is too long, a subclass of :exc:HTTPClientError.

.. exception:: HTTPUnsupportedMediaType :canonical: aiohttp.web_exceptions.HTTPUnsupportedMediaType

An exception for 415 Entity body in unsupported format, a subclass of :exc:HTTPClientError.

.. exception:: HTTPRequestRangeNotSatisfiable :canonical: aiohttp.web_exceptions.HTTPRequestRangeNotSatisfiable

An exception for 416 Cannot satisfy request range, a subclass of :exc:HTTPClientError.

.. exception:: HTTPExpectationFailed :canonical: aiohttp.web_exceptions.HTTPExpectationFailed

An exception for 417 Expect condition could not be satisfied, a subclass of :exc:HTTPClientError.

.. exception:: HTTPMisdirectedRequest :canonical: aiohttp.web_exceptions.HTTPMisdirectedRequest

An exception for 421 Misdirected Request, a subclass of :exc:HTTPClientError.

.. exception:: HTTPUnprocessableEntity :canonical: aiohttp.web_exceptions.HTTPUnprocessableEntity

An exception for 422 Unprocessable Entity, a subclass of :exc:HTTPClientError.

.. exception:: HTTPFailedDependency :canonical: aiohttp.web_exceptions.HTTPFailedDependency

An exception for 424 Failed Dependency, a subclass of :exc:HTTPClientError.

.. exception:: HTTPUpgradeRequired :canonical: aiohttp.web_exceptions.HTTPUpgradeRequired

An exception for 426 Upgrade Required, a subclass of :exc:HTTPClientError.

.. exception:: HTTPPreconditionRequired :canonical: aiohttp.web_exceptions.HTTPPreconditionRequired

An exception for 428 Precondition Required, a subclass of :exc:HTTPClientError.

.. exception:: HTTPTooManyRequests :canonical: aiohttp.web_exceptions.HTTPTooManyRequests

An exception for 429 Too Many Requests, a subclass of :exc:HTTPClientError.

.. exception:: HTTPRequestHeaderFieldsTooLarge :canonical: aiohttp.web_exceptions.HTTPRequestHeaderFieldsTooLarge

An exception for 431 Requests Header Fields Too Large, a subclass of :exc:HTTPClientError.

.. exception:: HTTPUnavailableForLegalReasons(link, *,
headers=None,
reason=None,
text=None,
content_type=None) :canonical: aiohttp.web_exceptions.HTTPUnavailableForLegalReasons

An exception for 451 Unavailable For Legal Reasons, a subclass of :exc:HTTPClientError.

:param link: A link to yourself (as the entity implementing the blockage), :class:str, :class:~yarl.URL or None.

For other parameters see :exc:HTTPException constructor. A reason for the block should be included in text.

.. attribute:: link

  A :class:`~yarl.URL` link to the entity implementing the blockage or ``None``,
  read-only property.

Server Errors

HTTP exceptions for status code in range 500-599, e.g. raise web.HTTPBadGateway().

.. exception:: HTTPServerError :canonical: aiohttp.web_exceptions.HTTPServerError

A base class for the category, a subclass of :exc:HTTPException.

.. exception:: HTTPInternalServerError :canonical: aiohttp.web_exceptions.HTTPInternalServerError

An exception for 500 Server got itself in trouble, a subclass of :exc:HTTPServerError.

.. exception:: HTTPNotImplemented :canonical: aiohttp.web_exceptions.HTTPNotImplemented

An exception for 501 Server does not support this operation, a subclass of :exc:HTTPServerError.

.. exception:: HTTPBadGateway :canonical: aiohttp.web_exceptions.HTTPBadGateway

An exception for 502 Invalid responses from another server/proxy, a subclass of :exc:HTTPServerError.

.. exception:: HTTPServiceUnavailable :canonical: aiohttp.web_exceptions.HTTPServiceUnavailable

An exception for 503 The server cannot process the request due to a high load, a subclass of :exc:HTTPServerError.

.. exception:: HTTPGatewayTimeout :canonical: aiohttp.web_exceptions.HTTPGatewayTimeout

An exception for 504 The gateway server did not receive a timely response, a subclass of :exc:HTTPServerError.

.. exception:: HTTPVersionNotSupported :canonical: aiohttp.web_exceptions.HTTPVersionNotSupported

An exception for 505 Cannot fulfill request, a subclass of :exc:HTTPServerError.

.. exception:: HTTPVariantAlsoNegotiates :canonical: aiohttp.web_exceptions.HTTPVariantAlsoNegotiates

An exception for 506 Variant Also Negotiates, a subclass of :exc:HTTPServerError.

.. exception:: HTTPInsufficientStorage :canonical: aiohttp.web_exceptions.HTTPInsufficientStorage

An exception for 507 Insufficient Storage, a subclass of :exc:HTTPServerError.

.. exception:: HTTPNotExtended :canonical: aiohttp.web_exceptions.HTTPNotExtended

An exception for 510 Not Extended, a subclass of :exc:HTTPServerError.

.. exception:: HTTPNetworkAuthenticationRequired :canonical: aiohttp.web_exceptions.HTTPNetworkAuthenticationRequired

An exception for 511 Network Authentication Required, a subclass of :exc:HTTPServerError.