initial implementation

Author: pmoegenburg

api/src/opentrons/protocols/api_support/util.py

@@ -22,6 +22,10 @@
 from opentrons.hardware_control.types import Axis
 from opentrons.hardware_control.util import ot2_axis_to_string
 from opentrons_shared_data.robot.dev_types import RobotType
+from opentrons_shared_data.errors.exceptions import (
+    APIRemoved,
+    IncorrectAPIVersion,
+)
 
 if TYPE_CHECKING:
     from opentrons.protocol_api.labware import Well, Labware
@@ -37,15 +41,15 @@
 MODULE_LOG = logging.getLogger(__name__)
 
 
-class APIVersionError(Exception):
+class APIVersionError(IncorrectAPIVersion):
     """
     Error raised when a protocol attempts to access behavior not implemented
     """
 
     pass
 
 
-class UnsupportedAPIError(Exception):
+class UnsupportedAPIError(APIRemoved):
     """Error raised when a protocol attempts to use unsupported API."""
 
 

shared-data/python/opentrons_shared_data/errors/codes.py

@@ -92,6 +92,7 @@ class ErrorCodes(Enum):
     INVALID_STORED_DATA = _code_from_dict_entry("4008")
     MISSING_CONFIGURATION_DATA = _code_from_dict_entry("4009")
     RUNTIME_PARAMETER_VALUE_REQUIRED = _code_from_dict_entry("4010")
+    INCORRECT_API_VERSION = _code_from_dict_entry("4011")
 
     @classmethod
     @lru_cache(25)

shared-data/python/opentrons_shared_data/errors/exceptions.py

@@ -921,6 +921,30 @@ def __init__(
         )
 
 
+class IncorrectAPIVersion(GeneralError):
+    """An error indicating that a command was issued that is not supported by the API version in use."""
+
+    def __init(
+        self,
+        api_element: str,
+        until_version: str,
+        message: Optional[str] = None,
+        detail: Optional[Dict[str, str]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build an IncorrectAPIVersion error."""
+        checked_detail: Dict[str, Any] = detail or {}
+        checked_detail["identifier"] = api_element
+        checked_detail["until_version"] = until_version
+        checked_message = (
+            message
+            or f"{api_element} is not available until version {until_version}."
+        )
+        super().__init__(
+            ErrorCodes.INCORRECT_API_VERSION, checked_message, checked_detail, wrapping
+        )
+
+
 class CommandPreconditionViolated(GeneralError):
     """An error indicating that a command was issued in a robot state incompatible with it."""