.. 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`.
