crypticorn 2.5.2__py3-none-any.whl → 2.6.0__py3-none-any.whl

crypticorn/common/errors.py

@@ -1,22 +1,6 @@
-from enum import Enum, EnumMeta, StrEnum
-import logging
+from enum import Enum, StrEnum
 from fastapi import status
-from crypticorn.common.mixins import ExcludeEnumMixin
-
-logger = logging.getLogger(__name__)
-
-
-class Fallback(EnumMeta):
-    """Fallback to UNKNOWN_ERROR for error codes not yet published to PyPI."""
-
-    def __getattr__(cls, name):
-        # Let Pydantic/internal stuff pass silently ! fragile
-        if name.startswith("__"):
-            raise AttributeError(name)
-        logger.warning(
-            f"Unknown error code '{name}' - update crypticorn package or check for typos"
-        )
-        return cls.UNKNOWN_ERROR
+from crypticorn.common.mixins import ExcludeEnumMixin, ApiErrorFallback
 
 
 class ApiErrorType(ExcludeEnumMixin, StrEnum):
@@ -37,7 +21,6 @@ class ApiErrorIdentifier(ExcludeEnumMixin, StrEnum):
 
     ALLOCATION_BELOW_EXPOSURE = "allocation_below_current_exposure"
     ALLOCATION_BELOW_MINIMUM = "allocation_below_min_amount"
-    ALPHANUMERIC_CHARACTERS_ONLY = "alphanumeric_characters_only"
     BLACK_SWAN = "black_swan"
     BOT_ALREADY_DELETED = "bot_already_deleted"
     BOT_DISABLED = "bot_disabled"
@@ -73,6 +56,7 @@ class ApiErrorIdentifier(ExcludeEnumMixin, StrEnum):
     INVALID_DATA_RESPONSE = "invalid_data_response"
     INVALID_EXCHANGE_KEY = "invalid_exchange_key"
     INVALID_MARGIN_MODE = "invalid_margin_mode"
+    INVALID_MODEL_NAME = "invalid_model_name"
     INVALID_PARAMETER = "invalid_parameter_provided"
     LEVERAGE_EXCEEDED = "leverage_limit_exceeded"
     LIQUIDATION_PRICE_VIOLATION = "order_violates_liquidation_price_constraints"
@@ -112,7 +96,7 @@ class ApiErrorIdentifier(ExcludeEnumMixin, StrEnum):
     URL_NOT_FOUND = "requested_resource_not_found"
 
     @property
-    def get_error_code(self) -> str:
+    def get_error(self) -> "ApiError":
         """Get the corresponding ApiError."""
         return ApiError[self.value]
 
@@ -126,7 +110,7 @@ class ApiErrorLevel(ExcludeEnumMixin, StrEnum):
     WARNING = "warning"
 
 
-class ApiError(ExcludeEnumMixin, Enum, metaclass=Fallback):
+class ApiError(ExcludeEnumMixin, Enum, metaclass=ApiErrorFallback):
     """API error codes. Fallback to UNKNOWN_ERROR for error codes not yet published to PyPI."""
 
     ALLOCATION_BELOW_EXPOSURE = (
@@ -139,11 +123,6 @@ class ApiError(ExcludeEnumMixin, Enum, metaclass=Fallback):
         ApiErrorType.USER_ERROR,
         ApiErrorLevel.ERROR,
     )
-    ALPHANUMERIC_CHARACTERS_ONLY = (
-        ApiErrorIdentifier.ALPHANUMERIC_CHARACTERS_ONLY,
-        ApiErrorType.USER_ERROR,
-        ApiErrorLevel.ERROR,
-    )
     BLACK_SWAN = (
         ApiErrorIdentifier.BLACK_SWAN,
         ApiErrorType.USER_ERROR,
@@ -284,6 +263,11 @@ class ApiError(ExcludeEnumMixin, Enum, metaclass=Fallback):
         ApiErrorType.USER_ERROR,
         ApiErrorLevel.ERROR,
     )
+    INVALID_MODEL_NAME = (
+        ApiErrorIdentifier.INVALID_MODEL_NAME,
+        ApiErrorType.USER_ERROR,
+        ApiErrorLevel.ERROR,
+    )
     INSUFFICIENT_SCOPES = (
         ApiErrorIdentifier.INSUFFICIENT_SCOPES,
         ApiErrorType.USER_ERROR,
@@ -492,7 +476,7 @@ class ApiError(ExcludeEnumMixin, Enum, metaclass=Fallback):
     )
     UNKNOWN_ERROR = (
         ApiErrorIdentifier.UNKNOWN_ERROR,
-        ApiErrorType.EXCHANGE_ERROR,
+        ApiErrorType.SERVER_ERROR,
         ApiErrorLevel.ERROR,
     )
     URL_NOT_FOUND = (
@@ -517,102 +501,325 @@ class ApiError(ExcludeEnumMixin, Enum, metaclass=Fallback):
         return self.value[2]
 
     @property
-    def status_code(self) -> int:
+    def http_code(self) -> int:
         """HTTP status code for the error."""
-        return HttpStatusMapper.get_status_code(self)
+        return StatusCodeMapper.get_http_code(self)
+
+    @property
+    def websocket_code(self) -> int:
+        """WebSocket status code for the error."""
+        return StatusCodeMapper.get_websocket_code(self)
 
 
-class HttpStatusMapper:
+class StatusCodeMapper:
     """Map API errors to HTTP status codes."""
 
     _mapping = {
         # Authentication/Authorization
-        ApiError.EXPIRED_BEARER: status.HTTP_401_UNAUTHORIZED,
-        ApiError.INVALID_BEARER: status.HTTP_401_UNAUTHORIZED,
-        ApiError.EXPIRED_API_KEY: status.HTTP_401_UNAUTHORIZED,
-        ApiError.INVALID_API_KEY: status.HTTP_401_UNAUTHORIZED,
-        ApiError.NO_CREDENTIALS: status.HTTP_401_UNAUTHORIZED,
-        ApiError.INSUFFICIENT_SCOPES: status.HTTP_403_FORBIDDEN,
-        ApiError.EXCHANGE_PERMISSION_DENIED: status.HTTP_403_FORBIDDEN,
-        ApiError.EXCHANGE_USER_FROZEN: status.HTTP_403_FORBIDDEN,
-        ApiError.TRADING_LOCKED: status.HTTP_403_FORBIDDEN,
-        ApiError.FORBIDDEN: status.HTTP_403_FORBIDDEN,
+        ApiError.EXPIRED_BEARER: (
+            status.HTTP_401_UNAUTHORIZED,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.INVALID_BEARER: (
+            status.HTTP_401_UNAUTHORIZED,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.EXPIRED_API_KEY: (
+            status.HTTP_401_UNAUTHORIZED,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.INVALID_API_KEY: (
+            status.HTTP_401_UNAUTHORIZED,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.NO_CREDENTIALS: (
+            status.HTTP_401_UNAUTHORIZED,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.INSUFFICIENT_SCOPES: (
+            status.HTTP_403_FORBIDDEN,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.EXCHANGE_PERMISSION_DENIED: (
+            status.HTTP_403_FORBIDDEN,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.EXCHANGE_USER_FROZEN: (
+            status.HTTP_403_FORBIDDEN,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.TRADING_LOCKED: (
+            status.HTTP_403_FORBIDDEN,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.FORBIDDEN: (
+            status.HTTP_403_FORBIDDEN,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
         # Not Found
-        ApiError.URL_NOT_FOUND: status.HTTP_404_NOT_FOUND,
-        ApiError.OBJECT_NOT_FOUND: status.HTTP_404_NOT_FOUND,
-        ApiError.ORDER_NOT_FOUND: status.HTTP_404_NOT_FOUND,
-        ApiError.POSITION_NOT_FOUND: status.HTTP_404_NOT_FOUND,
-        ApiError.SYMBOL_NOT_FOUND: status.HTTP_404_NOT_FOUND,
+        ApiError.URL_NOT_FOUND: (
+            status.HTTP_404_NOT_FOUND,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.OBJECT_NOT_FOUND: (
+            status.HTTP_404_NOT_FOUND,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.ORDER_NOT_FOUND: (
+            status.HTTP_404_NOT_FOUND,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.POSITION_NOT_FOUND: (
+            status.HTTP_404_NOT_FOUND,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.SYMBOL_NOT_FOUND: (
+            status.HTTP_404_NOT_FOUND,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
         # Conflicts/Duplicates
-        ApiError.CLIENT_ORDER_ID_REPEATED: status.HTTP_409_CONFLICT,
-        ApiError.OBJECT_ALREADY_EXISTS: status.HTTP_409_CONFLICT,
-        ApiError.EXCHANGE_KEY_ALREADY_EXISTS: status.HTTP_409_CONFLICT,
-        ApiError.BOT_ALREADY_DELETED: status.HTTP_409_CONFLICT,
-        ApiError.STRATEGY_ALREADY_EXISTS: status.HTTP_409_CONFLICT,
+        ApiError.CLIENT_ORDER_ID_REPEATED: (
+            status.HTTP_409_CONFLICT,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.OBJECT_ALREADY_EXISTS: (
+            status.HTTP_409_CONFLICT,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.EXCHANGE_KEY_ALREADY_EXISTS: (
+            status.HTTP_409_CONFLICT,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.BOT_ALREADY_DELETED: (
+            status.HTTP_409_CONFLICT,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.STRATEGY_ALREADY_EXISTS: (
+            status.HTTP_409_CONFLICT,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
         # Invalid Content
-        ApiError.CONTENT_TYPE_ERROR: status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
-        ApiError.INVALID_DATA_REQUEST: status.HTTP_422_UNPROCESSABLE_ENTITY,
-        ApiError.INVALID_DATA_RESPONSE: status.HTTP_422_UNPROCESSABLE_ENTITY,
+        ApiError.CONTENT_TYPE_ERROR: (
+            status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+            status.WS_1003_UNSUPPORTED_DATA,
+        ),
+        ApiError.INVALID_DATA_REQUEST: (
+            status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status.WS_1007_INVALID_FRAME_PAYLOAD_DATA,
+        ),
+        ApiError.INVALID_DATA_RESPONSE: (
+            status.HTTP_422_UNPROCESSABLE_ENTITY,
+            status.WS_1007_INVALID_FRAME_PAYLOAD_DATA,
+        ),
         # Rate Limits
-        ApiError.EXCHANGE_RATE_LIMIT: status.HTTP_429_TOO_MANY_REQUESTS,
-        ApiError.REQUEST_SCOPE_EXCEEDED: status.HTTP_429_TOO_MANY_REQUESTS,
+        ApiError.EXCHANGE_RATE_LIMIT: (
+            status.HTTP_429_TOO_MANY_REQUESTS,
+            status.WS_1013_TRY_AGAIN_LATER,
+        ),
+        ApiError.REQUEST_SCOPE_EXCEEDED: (
+            status.HTTP_429_TOO_MANY_REQUESTS,
+            status.WS_1013_TRY_AGAIN_LATER,
+        ),
         # Server Errors
-        ApiError.UNKNOWN_ERROR: status.HTTP_500_INTERNAL_SERVER_ERROR,
-        ApiError.EXCHANGE_SYSTEM_ERROR: status.HTTP_500_INTERNAL_SERVER_ERROR,
-        ApiError.NOW_API_DOWN: status.HTTP_500_INTERNAL_SERVER_ERROR,
-        ApiError.RPC_TIMEOUT: status.HTTP_500_INTERNAL_SERVER_ERROR,
+        ApiError.UNKNOWN_ERROR: (
+            status.HTTP_500_INTERNAL_SERVER_ERROR,
+            status.WS_1011_INTERNAL_ERROR,
+        ),
+        ApiError.EXCHANGE_SYSTEM_ERROR: (
+            status.HTTP_500_INTERNAL_SERVER_ERROR,
+            status.WS_1011_INTERNAL_ERROR,
+        ),
+        ApiError.NOW_API_DOWN: (
+            status.HTTP_500_INTERNAL_SERVER_ERROR,
+            status.WS_1011_INTERNAL_ERROR,
+        ),
+        ApiError.RPC_TIMEOUT: (
+            status.HTTP_500_INTERNAL_SERVER_ERROR,
+            status.WS_1011_INTERNAL_ERROR,
+        ),
         # Service Unavailable
-        ApiError.EXCHANGE_SERVICE_UNAVAILABLE: status.HTTP_503_SERVICE_UNAVAILABLE,
-        ApiError.EXCHANGE_MAINTENANCE: status.HTTP_503_SERVICE_UNAVAILABLE,
-        ApiError.EXCHANGE_SYSTEM_BUSY: status.HTTP_503_SERVICE_UNAVAILABLE,
-        ApiError.SETTLEMENT_IN_PROGRESS: status.HTTP_503_SERVICE_UNAVAILABLE,
-        ApiError.POSITION_SUSPENDED: status.HTTP_503_SERVICE_UNAVAILABLE,
-        ApiError.TRADING_SUSPENDED: status.HTTP_503_SERVICE_UNAVAILABLE,
+        ApiError.EXCHANGE_SERVICE_UNAVAILABLE: (
+            status.HTTP_503_SERVICE_UNAVAILABLE,
+            status.WS_1011_INTERNAL_ERROR,
+        ),
+        ApiError.EXCHANGE_MAINTENANCE: (
+            status.HTTP_503_SERVICE_UNAVAILABLE,
+            status.WS_1011_INTERNAL_ERROR,
+        ),
+        ApiError.EXCHANGE_SYSTEM_BUSY: (
+            status.HTTP_503_SERVICE_UNAVAILABLE,
+            status.WS_1011_INTERNAL_ERROR,
+        ),
+        ApiError.SETTLEMENT_IN_PROGRESS: (
+            status.HTTP_503_SERVICE_UNAVAILABLE,
+            status.WS_1011_INTERNAL_ERROR,
+        ),
+        ApiError.POSITION_SUSPENDED: (
+            status.HTTP_503_SERVICE_UNAVAILABLE,
+            status.WS_1011_INTERNAL_ERROR,
+        ),
+        ApiError.TRADING_SUSPENDED: (
+            status.HTTP_503_SERVICE_UNAVAILABLE,
+            status.WS_1011_INTERNAL_ERROR,
+        ),
         # Bad Requests (400) - Invalid parameters or states
-        ApiError.ALPHANUMERIC_CHARACTERS_ONLY: status.HTTP_400_BAD_REQUEST,
-        ApiError.ALLOCATION_BELOW_EXPOSURE: status.HTTP_400_BAD_REQUEST,
-        ApiError.ALLOCATION_BELOW_MINIMUM: status.HTTP_400_BAD_REQUEST,
-        ApiError.BLACK_SWAN: status.HTTP_400_BAD_REQUEST,
-        ApiError.BOT_DISABLED: status.HTTP_400_BAD_REQUEST,
-        ApiError.DELETE_BOT_ERROR: status.HTTP_400_BAD_REQUEST,
-        ApiError.EXCHANGE_INVALID_SIGNATURE: status.HTTP_400_BAD_REQUEST,
-        ApiError.EXCHANGE_INVALID_TIMESTAMP: status.HTTP_400_BAD_REQUEST,
-        ApiError.EXCHANGE_IP_RESTRICTED: status.HTTP_400_BAD_REQUEST,
-        ApiError.EXCHANGE_KEY_IN_USE: status.HTTP_400_BAD_REQUEST,
-        ApiError.EXCHANGE_SYSTEM_CONFIG_ERROR: status.HTTP_400_BAD_REQUEST,
-        ApiError.HEDGE_MODE_NOT_ACTIVE: status.HTTP_400_BAD_REQUEST,
-        ApiError.HTTP_ERROR: status.HTTP_400_BAD_REQUEST,
-        ApiError.INSUFFICIENT_BALANCE: status.HTTP_400_BAD_REQUEST,
+        ApiError.INVALID_MODEL_NAME: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.ALLOCATION_BELOW_EXPOSURE: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.ALLOCATION_BELOW_MINIMUM: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.BLACK_SWAN: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.BOT_DISABLED: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.DELETE_BOT_ERROR: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.EXCHANGE_INVALID_SIGNATURE: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.EXCHANGE_INVALID_TIMESTAMP: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.EXCHANGE_IP_RESTRICTED: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.EXCHANGE_KEY_IN_USE: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.EXCHANGE_SYSTEM_CONFIG_ERROR: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.HEDGE_MODE_NOT_ACTIVE: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.HTTP_ERROR: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.INSUFFICIENT_BALANCE: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
         ApiError.INSUFFICIENT_MARGIN: status.HTTP_400_BAD_REQUEST,
-        ApiError.INVALID_EXCHANGE_KEY: status.HTTP_400_BAD_REQUEST,
-        ApiError.INVALID_MARGIN_MODE: status.HTTP_400_BAD_REQUEST,
-        ApiError.INVALID_PARAMETER: status.HTTP_400_BAD_REQUEST,
-        ApiError.LEVERAGE_EXCEEDED: status.HTTP_400_BAD_REQUEST,
+        ApiError.INVALID_EXCHANGE_KEY: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.INVALID_MARGIN_MODE: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.INVALID_PARAMETER: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.LEVERAGE_EXCEEDED: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
         ApiError.LIQUIDATION_PRICE_VIOLATION: status.HTTP_400_BAD_REQUEST,
-        ApiError.ORDER_ALREADY_FILLED: status.HTTP_400_BAD_REQUEST,
-        ApiError.ORDER_IN_PROCESS: status.HTTP_400_BAD_REQUEST,
-        ApiError.ORDER_LIMIT_EXCEEDED: status.HTTP_400_BAD_REQUEST,
-        ApiError.ORDER_PRICE_INVALID: status.HTTP_400_BAD_REQUEST,
-        ApiError.ORDER_SIZE_TOO_LARGE: status.HTTP_400_BAD_REQUEST,
-        ApiError.ORDER_SIZE_TOO_SMALL: status.HTTP_400_BAD_REQUEST,
-        ApiError.POSITION_LIMIT_EXCEEDED: status.HTTP_400_BAD_REQUEST,
-        ApiError.POST_ONLY_REJECTED: status.HTTP_400_BAD_REQUEST,
-        ApiError.RISK_LIMIT_EXCEEDED: status.HTTP_400_BAD_REQUEST,
-        ApiError.STRATEGY_DISABLED: status.HTTP_400_BAD_REQUEST,
-        ApiError.STRATEGY_LEVERAGE_MISMATCH: status.HTTP_400_BAD_REQUEST,
-        ApiError.STRATEGY_NOT_SUPPORTING_EXCHANGE: status.HTTP_400_BAD_REQUEST,
-        ApiError.TRADING_ACTION_EXPIRED: status.HTTP_400_BAD_REQUEST,
-        ApiError.TRADING_ACTION_SKIPPED: status.HTTP_400_BAD_REQUEST,
+        ApiError.ORDER_ALREADY_FILLED: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.ORDER_IN_PROCESS: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.ORDER_LIMIT_EXCEEDED: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.ORDER_PRICE_INVALID: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.ORDER_SIZE_TOO_LARGE: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.ORDER_SIZE_TOO_SMALL: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.POSITION_LIMIT_EXCEEDED: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.POST_ONLY_REJECTED: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.RISK_LIMIT_EXCEEDED: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.STRATEGY_DISABLED: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.STRATEGY_LEVERAGE_MISMATCH: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.STRATEGY_NOT_SUPPORTING_EXCHANGE: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.TRADING_ACTION_EXPIRED: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
+        ApiError.TRADING_ACTION_SKIPPED: (
+            status.HTTP_400_BAD_REQUEST,
+            status.WS_1008_POLICY_VIOLATION,
+        ),
         # Success cases
-        ApiError.SUCCESS: status.HTTP_200_OK,
-        ApiError.BOT_STOPPING_COMPLETED: status.HTTP_200_OK,
-        ApiError.BOT_STOPPING_STARTED: status.HTTP_200_OK,
-        ApiError.OBJECT_CREATED: status.HTTP_201_CREATED,
-        ApiError.OBJECT_UPDATED: status.HTTP_200_OK,
-        ApiError.OBJECT_DELETED: status.HTTP_204_NO_CONTENT,
+        ApiError.SUCCESS: (status.HTTP_200_OK, status.WS_1000_NORMAL_CLOSURE),
+        ApiError.BOT_STOPPING_COMPLETED: (
+            status.HTTP_200_OK,
+            status.WS_1000_NORMAL_CLOSURE,
+        ),
+        ApiError.BOT_STOPPING_STARTED: (
+            status.HTTP_200_OK,
+            status.WS_1000_NORMAL_CLOSURE,
+        ),
+        ApiError.OBJECT_CREATED: (
+            status.HTTP_201_CREATED,
+            status.WS_1000_NORMAL_CLOSURE,
+        ),
+        ApiError.OBJECT_UPDATED: (status.HTTP_200_OK, status.WS_1000_NORMAL_CLOSURE),
+        ApiError.OBJECT_DELETED: (
+            status.HTTP_204_NO_CONTENT,
+            status.WS_1000_NORMAL_CLOSURE,
+        ),
     }
 
     @classmethod
-    def get_status_code(cls, error: ApiError) -> int:
+    def get_http_code(cls, error: ApiError) -> int:
         """Get the HTTP status code for the error. If the error is not in the mapping, return 500."""
-        return cls._mapping.get(error, status.HTTP_500_INTERNAL_SERVER_ERROR)
+        return cls._mapping.get(error, cls._mapping[ApiError.UNKNOWN_ERROR])[0]
+
+    @classmethod
+    def get_websocket_code(cls, error: ApiError) -> int:
+        """Get the WebSocket status code for the error. If the error is not in the mapping, return 1008."""
+        return cls._mapping.get(error, cls._mapping[ApiError.UNKNOWN_ERROR])[1]

crypticorn/common/exceptions.py

@@ -1,4 +1,5 @@
-from typing import Optional, Dict, Any
+from typing import Optional, Dict, Any, Literal
+from enum import StrEnum
 from pydantic import BaseModel, Field
 from fastapi import HTTPException as FastAPIHTTPException, Request, FastAPI
 from fastapi.exceptions import RequestValidationError, ResponseValidationError
@@ -6,6 +7,11 @@ from fastapi.responses import JSONResponse
 from crypticorn.common import ApiError, ApiErrorIdentifier, ApiErrorType, ApiErrorLevel
 
 
+class ExceptionType(StrEnum):
+    HTTP = "http"
+    WEBSOCKET = "websocket"
+
+
 class ExceptionDetail(BaseModel):
     """This is the detail of the exception. It is used to enrich the exception with additional information by unwrapping the ApiError into its components."""
 
@@ -24,13 +30,19 @@ class ExceptionContent(BaseModel):
     message: Optional[str] = Field(None, description="An additional error message")
     details: Any = Field(None, description="Additional details about the error")
 
-    def enrich(self) -> ExceptionDetail:
+    def enrich(
+        self, _type: Optional[ExceptionType] = ExceptionType.HTTP
+    ) -> ExceptionDetail:
         return ExceptionDetail(
             message=self.message,
             code=self.error.identifier,
             type=self.error.type,
             level=self.error.level,
-            status_code=self.error.status_code,
+            status_code=(
+                self.error.http_code
+                if _type == ExceptionType.HTTP
+                else self.error.websocket_code
+            ),
             details=self.details,
         )
 
@@ -45,9 +57,12 @@ class HTTPException(FastAPIHTTPException):
         self,
         content: ExceptionContent,
         headers: Optional[Dict[str, str]] = None,
+        _type: Optional[ExceptionType] = ExceptionType.HTTP,
     ):
+        self.content = content
+        self.headers = headers
         assert isinstance(content, ExceptionContent)
-        body = content.enrich()
+        body = content.enrich(_type)
         super().__init__(
             status_code=body.status_code,
             detail=body.model_dump(mode="json"),
@@ -55,6 +70,25 @@ class HTTPException(FastAPIHTTPException):
         )
 
 
+class WebSocketException(HTTPException):
+    """A WebSocketException is to be used for WebSocket connections. It is a wrapper around the HTTPException class to maintain the same structure, but using a different status code.
+    To be used in the same way as the HTTPException.
+    """
+
+    def __init__(
+        self, content: ExceptionContent, headers: Optional[Dict[str, str]] = None
+    ):
+        super().__init__(content, headers, _type=ExceptionType.WEBSOCKET)
+
+    @classmethod
+    def from_http_exception(cls, http_exception: HTTPException):
+        """This is a helper method to convert an HTTPException to a WebSocketException."""
+        return WebSocketException(
+            content=http_exception.content,
+            headers=http_exception.headers,
+        )
+
+
 async def general_handler(request: Request, exc: Exception):
     """This is the default exception handler for all exceptions."""
     body = ExceptionContent(message=str(exc), error=ApiError.UNKNOWN_ERROR)

crypticorn/common/mixins.py

@@ -1,3 +1,9 @@
+from enum import EnumMeta
+import logging
+
+logger = logging.getLogger("uvicorn")
+
+
 class ValidateEnumMixin:
     """
     Mixin for validating enum values manually.
@@ -35,3 +41,16 @@ class ExcludeEnumMixin:
         schema = handler(core_schema)
         schema.pop("enum", None)
         return schema
+
+
+class ApiErrorFallback(EnumMeta):
+    """Fallback for enum members that are not yet published to PyPI."""
+
+    def __getattr__(cls, name):
+        # Let Pydantic/internal stuff pass silently ! fragile
+        if name.startswith("__"):
+            raise AttributeError(name)
+        logger.warning(
+            f"Unknown enum member '{name}' - update crypticorn package or check for typos"
+        )
+        return cls.UNKNOWN_ERROR

crypticorn/common/pagination.py

@@ -0,0 +1,49 @@
+from typing import Generic, Type, TypeVar, List, Optional, Literal
+from pydantic import BaseModel, Field, model_validator
+
+T = TypeVar("T")
+
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    """Pydantic model for paginated response
+    >>> PaginatedResponse[ItemModel](data=items, total=total_items, page=1, size=10, prev=None, next=2)
+    """
+
+    data: List[T]
+    total: int = Field(description="The total number of items")
+    page: int = Field(description="The current page number")
+    size: int = Field(description="The number of items per page")
+    prev: Optional[int] = Field(None, description="The previous page number")
+    next: Optional[int] = Field(None, description="The next page number")
+
+
+class PaginationParams(BaseModel, Generic[T]):
+    """Standard pagination parameters for usage in API endpoints. Check the [fastapi docs](https://fastapi.tiangolo.com/tutorial/query-param-models/?h=qu#query-parameters-with-a-pydantic-model) for usage examples.
+    The default size is 10 items per page, but can be overridden:
+    >>> class HeavyPaginationParams(PaginationParams[T]):
+    >>>     size: int = Field(default=100, description="The number of items per page")
+    """
+
+    page: int = Field(default=1, description="The current page number")
+    size: int = Field(default=10, description="The number of items per page")
+    order: Literal["asc", "desc"] = Field(
+        default="asc", description="The order to sort by"
+    )
+    sort: Optional[str] = Field(None, description="The field to sort by")
+
+    @model_validator(mode="after")
+    def validate(self):
+        # Extract the generic argument type
+        args: tuple = self.__pydantic_generic_metadata__.get("args")
+        if not args or not issubclass(args[0], BaseModel):
+            raise TypeError(
+                "PaginationParams must be used with a Pydantic BaseModel as a generic parameter"
+            )
+        if self.sort:
+            # check if the sort field is valid
+            model: Type[BaseModel] = args[0]
+            if self.sort and self.sort not in model.model_fields:
+                raise ValueError(
+                    f"Invalid sort field: '{self.sort}' — must be one of: {list(model.model_fields)}"
+                )
+        return self