Exceptions

HTTP and WebSocket exception classes.

Exception classes for genro-asgi HTTP and WebSocket error handling.

This module provides typed exceptions for signaling errors in the HTTP request/response cycle and WebSocket connections. These exceptions are designed to be caught by the framework and converted to appropriate HTTP responses or WebSocket close frames.

Module Structure

Three exception classes, all inheriting directly from Exception:

HTTPException - For HTTP error responses (4xx, 5xx)
WebSocketException - For closing WebSocket with error code
WebSocketDisconnect - Signal that client disconnected (not an error)

Design Decisions

No validation: status_code and code are not validated. Users are expected to use appropriate values (4xx/5xx for HTTP, 1000-4999 for WebSocket).
No __slots__: Exceptions are short-lived and don’t benefit significantly from __slots__. This also maintains compatibility with Exception base class.
No common base: Each exception inherits directly from Exception for simplicity. Use tuple syntax for catching multiple: except (HTTPException, WebSocketException)
headers: Accepts both dict[str, str] for simple headers and list[tuple[str, str]] for headers that may have duplicate names (e.g., multiple Set-Cookie headers).

HTTPException

Raise in handlers to return an HTTP error response.

genro_asgi.exceptions.status_code

HTTP status code (expected 4xx or 5xx)

Type:: int

genro_asgi.exceptions.detail

Error detail message (default: “”)

Type:: str

genro_asgi.exceptions.headers

Optional response headers as list of tuples. Supports duplicate header names (e.g., multiple Set-Cookie). Input can be dict[str, str] or list[tuple[str, str]], stored as list.

Type:: list[tuple[str, str]] | None

Example

>>> raise HTTPException(404, detail="User not found")
>>> raise HTTPException(401, detail="Auth required", headers={"WWW-Authenticate": "Bearer"})
>>> raise HTTPException(400, headers=[("Set-Cookie", "a=1"), ("Set-Cookie", "b=2")])

WebSocketException

Raise to close a WebSocket connection with an error code.

WebSocket close codes (RFC 6455):: 1000 - Normal closure 1001 - Going away 1002 - Protocol error 1003 - Unsupported data 1007 - Invalid payload 1008 - Policy violation 1009 - Message too big 1011 - Internal error 4000-4999 - Application-specific (free to use)

genro_asgi.exceptions.code

WebSocket close code (default: 1000)

Type:: int

genro_asgi.exceptions.reason

Close reason message (default: “”)

Type:: str

Example

>>> raise WebSocketException(code=4000, reason="Invalid message format")
>>> raise WebSocketException(code=1008, reason="Rate limit exceeded")

WebSocketDisconnect

Raised by the framework when a WebSocket client disconnects. This is NOT an error - it’s a signal for cleanup.

genro_asgi.exceptions.code

WebSocket close code sent by client (default: 1000)

Type:: int

genro_asgi.exceptions.reason

Close reason from client (default: “”)

Type:: str

Example

>>> try:
...     data = await websocket.receive_text()
... except WebSocketDisconnect:
...     logger.info("Client disconnected normally")

Difference between WebSocketException and WebSocketDisconnect:

WebSocketException:

Raised BY the server code (explicit raise)

Semantics: “I want to close this connection with an error”

Typical handling: Log error, cleanup

WebSocketDisconnect:

Raised BY the framework (when receive fails)

Semantics: “The client has disconnected”

Typical handling: Normal cleanup, no error logging

Usage Pattern:

>>> async def websocket_handler(websocket):
...     try:
...         while True:
...             msg = await websocket.receive_json()
...             if not validate(msg):
...                 raise WebSocketException(4000, "Invalid format")
...             await process(msg)
...     except WebSocketDisconnect:
...         logger.info("Client left")
...     except WebSocketException as e:
...         logger.error(f"WebSocket error: {e.code} - {e.reason}")

exception genro_asgi.exceptions.HTTPBadRequest(detail='Bad request')[source]

Bases: HTTPException

HTTP 400 Bad Request exception.

exception genro_asgi.exceptions.HTTPException(status_code, detail='', headers=None)[source]

Bases: Exception

HTTP exception with status code and detail.

Raise this in handlers to return an HTTP error response. The framework will catch this and convert it to an appropriate HTTP response with the given status code, detail, and headers.

status_code: HTTP status code (expected 4xx or 5xx, not validated)

detail: Error detail message

headers: Response headers as list of tuples (supports duplicate names)

Example

>>> raise HTTPException(404, detail="User not found")
>>> raise HTTPException(401, headers={"WWW-Authenticate": "Bearer"})
>>> raise HTTPException(400, headers=[("Set-Cookie", "a=1"), ("Set-Cookie", "b=2")])

__init__(status_code, detail='', headers=None)[source]

Initialize HTTP exception.

Parameters:

status_code (int) – HTTP status code (4xx, 5xx expected)
detail (str) – Error detail message (default: “”)
headers (dict[str, str] | list[tuple[str, str]] | None) – Response headers as dict or list of tuples (default: None). Dict is converted to list internally to support duplicate names.

exception genro_asgi.exceptions.HTTPForbidden(detail='Forbidden')[source]

Bases: HTTPException

HTTP 403 Forbidden exception.

exception genro_asgi.exceptions.HTTPNotFound(detail='Not found')[source]

Bases: HTTPException

HTTP 404 Not Found exception.

exception genro_asgi.exceptions.HTTPServiceUnavailable(detail='Service unavailable')[source]

Bases: HTTPException

HTTP 503 Service Unavailable exception.

exception genro_asgi.exceptions.HTTPUnauthorized(detail='Unauthorized')[source]

Bases: HTTPException

HTTP 401 Unauthorized exception.

exception genro_asgi.exceptions.Redirect(url, status_code=302)[source]

Bases: HTTPException

HTTP redirect exception. Raises 302 redirect by default.

exception genro_asgi.exceptions.WebSocketDisconnect(code=1000, reason='')[source]

Bases: Exception

Raised when a WebSocket is disconnected by the client.

This is not an error, just a signal that the connection was closed. The framework raises this when a receive operation fails because the client has disconnected.

code: WebSocket close code from client

reason: Close reason from client (if any)

Example

>>> try:
...     data = await websocket.receive_text()
... except WebSocketDisconnect as e:
...     print(f"Client disconnected: {e.code}")

__init__(code=1000, reason='')[source]

Initialize disconnect exception.

Parameters:

code (int) – WebSocket close code (default: 1000)
reason (str) – Close reason (default: “”)

exception genro_asgi.exceptions.WebSocketException(code=1000, reason='')[source]

Bases: Exception

WebSocket exception with close code and reason.

Raise this to close a WebSocket connection with an error code. The framework will catch this and send a close frame with the given code and reason.

code: WebSocket close code (1000-4999, not validated)

reason: Close reason message

Example

>>> raise WebSocketException(code=4000, reason="Invalid message")

__init__(code=1000, reason='')[source]

Initialize WebSocket exception.

Parameters:

code (int) – WebSocket close code (default: 1000)
reason (str) – Close reason message (default: “”)