Added InsufficientBalanceError

archipy/helpers/utils/app_utils.py

@@ -230,14 +230,18 @@ def create_fastapi_app(
         config: BaseConfig | None = None,
         *,
         configure_exception_handlers: bool = True,
+        include_common_responses: bool = True,
         lifespan: Callable[..., AbstractAsyncContextManager] | None = None,
     ) -> FastAPI:
-        """Creates and configures a FastAPI application.
+        """Create and configure a FastAPI application.
 
         Args:
-            config (BaseConfig | None): Optional custom configuration. If not provided, uses global config.
-            configure_exception_handlers (bool): Whether to configure exception handlers.
-            lifespan: Callable[..., AbstractAsyncContextManager] | None = None,
+            config (BaseConfig | None, optional): Custom configuration. If not provided, uses global config.
+            configure_exception_handlers (bool, optional): Whether to configure exception handlers. Defaults to True.
+            include_common_responses (bool, optional): Whether to configure common response definitions for all endpoints.
+                                                Defaults to True.
+            lifespan (Callable[..., AbstractAsyncContextManager] | None, optional): Custom lifespan context manager for the app.
+                                                                          Defaults to None.
 
         Returns:
             FastAPI: The configured FastAPI application instance.
@@ -255,7 +259,7 @@ def create_fastapi_app(
             swagger_ui_parameters=config.FASTAPI.SWAGGER_UI_PARAMS,
             docs_url=config.FASTAPI.DOCS_URL,
             redocs_url=config.FASTAPI.RE_DOCS_URL,
-            responses=cast(dict[int | str, Any], common_responses),
+            responses=cast(dict[int | str, Any], common_responses) if include_common_responses else None,
             lifespan=lifespan,
         )
 

archipy/models/errors/custom_errors.py

@@ -640,3 +640,20 @@ def __init__(
             error: The error detail or message.
         """
         super().__init__(error, lang, additional_data={"requirements": requirements} if requirements else None)
+
+
+class InsufficientBalanceError(BaseError):
+    """Exception raised when an operation fails due to insufficient account balance."""
+
+    def __init__(
+        self,
+        lang: LanguageType = LanguageType.FA,
+        error: ErrorDetailDTO = ErrorMessageType.INSUFFICIENT_BALANCE.value,
+    ) -> None:
+        """Initializes the exception.
+
+        Args:
+            lang: Language code for the error message (defaults to Persian).
+            error: The error detail or message.
+        """
+        super().__init__(error, lang)

archipy/models/types/error_message_types.py

@@ -196,6 +196,14 @@ class ErrorMessageType(Enum):
         grpc_status=StatusCode.CANCELLED if GRPC_AVAILABLE else None,
     )
 
+    INSUFFICIENT_BALANCE = ErrorDetailDTO.create_error_detail(
+        code="INSUFFICIENT_BALANCE",
+        message_en="Insufficient balance for operation",
+        message_fa="عدم موجودی کافی برای عملیات.",
+        http_status=HTTPStatus.PAYMENT_REQUIRED if HTTP_AVAILABLE else None,
+        grpc_status=StatusCode.FAILED_PRECONDITION if GRPC_AVAILABLE else None,
+    )
+
     # System Errors (500, 501, 503)
     INVALID_ENTITY_TYPE = ErrorDetailDTO.create_error_detail(
         code="INVALID_ENTITY",