Exceptions

websockets.exceptions defines the following exception hierarchy:

• WebSocketException

  • ConnectionClosed

    • ConnectionClosedError

    • ConnectionClosedOK

  • InvalidHandshake

    • SecurityError

    • InvalidMessage

    • InvalidHeader

      • InvalidHeaderFormat

      • InvalidHeaderValue

      • InvalidOrigin

      • InvalidUpgrade

    • InvalidStatus

    • InvalidStatusCode (legacy)

    • NegotiationError

      • DuplicateParameter

      • InvalidParameterName

      • InvalidParameterValue

    • AbortHandshake

    • RedirectHandshake

  • InvalidState

  • InvalidURI

  • PayloadTooBig

  • ProtocolError

exception websockets.exceptions.AbortHandshake(status, headers, body=b'')

Raised to abort the handshake on purpose and return an HTTP response.

This exception is an implementation detail.

The public API is process_request().

status

HTTP status code.

Type:

HTTPStatus

headers

HTTP response headers.

Type:

Headers

body

HTTP response body.

Type:

bytes

exception websockets.exceptions.ConnectionClosed(rcvd, sent, rcvd_then_sent=None)

Raised when trying to interact with a closed connection.

rcvd

if a close frame was received, its code and reason are available in rcvd.code and rcvd.reason.

Type:

Close | None

sent

if a close frame was sent, its code and reason are available in sent.code and sent.reason.

Type:

Close | None

rcvd_then_sent

if close frames were received and sent, this attribute tells in which order this happened, from the perspective of this side of the connection.

Type:

bool | None

exception websockets.exceptions.ConnectionClosedError(rcvd, sent, rcvd_then_sent=None)

Like ConnectionClosed, when the connection terminated with an error.

A close frame with a code other than 1000 (OK) or 1001 (going away) was received or sent, or the closing handshake didn’t complete properly.

exception websockets.exceptions.ConnectionClosedOK(rcvd, sent, rcvd_then_sent=None)

Like ConnectionClosed, when the connection terminated properly.

A close code with code 1000 (OK) or 1001 (going away) or without a code was received and sent.

exception websockets.exceptions.DuplicateParameter(name)

Raised when a parameter name is repeated in an extension header.

exception websockets.exceptions.InvalidHandshake

Raised during the handshake when the WebSocket connection fails.

exception websockets.exceptions.InvalidHeader(name, value=None)

Raised when an HTTP header doesn’t have a valid format or value.

exception websockets.exceptions.InvalidHeaderFormat(name, error, header, pos)

Raised when an HTTP header cannot be parsed.

The format of the header doesn’t match the grammar for that header.

exception websockets.exceptions.InvalidHeaderValue(name, value=None)

Raised when an HTTP header has a wrong value.

The format of the header is correct but a value isn’t acceptable.

exception websockets.exceptions.InvalidMessage

Raised when a handshake request or response is malformed.

exception websockets.exceptions.InvalidOrigin(origin)

Raised when the Origin header in a request isn’t allowed.

exception websockets.exceptions.InvalidParameterName(name)

Raised when a parameter name in an extension header is invalid.

exception websockets.exceptions.InvalidParameterValue(name, value)

Raised when a parameter value in an extension header is invalid.

exception websockets.exceptions.InvalidState

Raised when an operation is forbidden in the current state.

This exception is an implementation detail.

It should never be raised in normal circumstances.

exception websockets.exceptions.InvalidStatus(response)

Raised when a handshake response rejects the WebSocket upgrade.

exception websockets.exceptions.InvalidStatusCode(status_code, headers)

Raised when a handshake response status code is invalid.

exception websockets.exceptions.InvalidURI(uri, msg)

Raised when connecting to a URI that isn’t a valid WebSocket URI.

exception websockets.exceptions.InvalidUpgrade(name, value=None)

Raised when the Upgrade or Connection header isn’t correct.

exception websockets.exceptions.NegotiationError

Raised when negotiating an extension fails.

exception websockets.exceptions.PayloadTooBig

Raised when receiving a frame with a payload exceeding the maximum size.

exception websockets.exceptions.ProtocolError

Raised when a frame breaks the protocol.

exception websockets.exceptions.RedirectHandshake(uri)

Raised when a handshake gets redirected.

This exception is an implementation detail.

exception websockets.exceptions.SecurityError

Raised when a handshake request or response breaks a security rule.

Security limits are hard coded.

exception websockets.exceptions.WebSocketException

Base class for all exceptions defined by websockets.

websockets.exceptions.WebSocketProtocolError

alias of ProtocolError