feat(robot-server): Present error codes in error responses

robot-server/robot_server/commands/get_default_engine.py

@@ -6,6 +6,8 @@
 from opentrons.hardware_control import HardwareControlAPI
 from opentrons.protocol_engine import ProtocolEngine
 
+from opentrons_shared_data.errors import ErrorCodes
+
 from robot_server.errors import ErrorDetails
 from robot_server.hardware import get_hardware
 from robot_server.runs import EngineStore, EngineConflictError, get_engine_store
@@ -24,6 +26,7 @@ class RunActive(ErrorDetails):
         "There is an active run. Close the current run"
         " to issue commands via POST /commands."
     )
+    errorCode: str = ErrorCodes.ROBOT_IN_USE.value.code
 
 
 async def get_default_engine(
@@ -35,7 +38,7 @@ async def get_default_engine(
     try:
         engine = await engine_store.get_default_engine()
     except EngineConflictError as e:
-        raise RunActive().as_error(status.HTTP_409_CONFLICT) from e
+        raise RunActive.from_exc(e).as_error(status.HTTP_409_CONFLICT) from e
 
     attached_modules = hardware_api.attached_modules
     attached_module_spec = {

robot-server/robot_server/commands/router.py

@@ -7,6 +7,7 @@
 
 from opentrons.protocol_engine import ProtocolEngine, CommandIntent
 from opentrons.protocol_engine.errors import CommandDoesNotExistError
+from opentrons_shared_data.errors import ErrorCodes
 
 from robot_server.errors import ErrorDetails, ErrorBody
 from robot_server.service.json_api import (
@@ -31,6 +32,7 @@ class CommandNotFound(ErrorDetails):
 
     id: Literal["StatelessCommandNotFound"] = "StatelessCommandNotFound"
     title: str = "Stateless Command Not Found"
+    errorCode: str = ErrorCodes.GENERAL_ERROR.value.code
 
 
 @commands_router.post(
@@ -177,7 +179,7 @@ async def get_command(
         command = engine.state_view.commands.get(commandId)
 
     except CommandDoesNotExistError as e:
-        raise CommandNotFound(detail=str(e)).as_error(status.HTTP_404_NOT_FOUND) from e
+        raise CommandNotFound.from_exc(e).as_error(status.HTTP_404_NOT_FOUND) from e
 
     return await PydanticResponse.create(
         content=SimpleBody.construct(data=cast(StatelessCommand, command)),

robot-server/robot_server/errors/error_responses.py

@@ -1,9 +1,10 @@
 """JSON API errors and response models."""
 from pydantic import BaseModel, Field
 from pydantic.generics import GenericModel
-from typing import Any, Dict, Generic, Optional, Sequence, Tuple, TypeVar
+from typing import Any, Dict, Generic, Optional, Sequence, TypeVar, Type
 
 from robot_server.service.json_api import BaseResponseBody, ResourceLinks
+from opentrons_shared_data.errors import EnumeratedError, PythonException, ErrorCodes
 
 
 class ApiError(Exception):
@@ -105,6 +106,40 @@ def get_some_model():
             "occurrence of the error"
         ),
     )
+    errorCode: str = Field(
+        ErrorCodes.GENERAL_ERROR.value.code,
+        description=("The Opentrons error code associated with the error"),
+    )
+
+    @classmethod
+    def from_exc(
+        cls: Type["ErrorDetailsT"], exc: BaseException, **supplemental_kwargs: Any
+    ) -> "ErrorDetailsT":
+        """Build an ErrorDetails model from an exception.
+
+        To allow for custom child models of the ErrorDetails base setting separate
+        defaults, if a default is set for a given field it won't be set from the
+        exception unless override_defaults is True.
+        """
+        values = {k: v for k, v in supplemental_kwargs.items()}
+        if not isinstance(exc, EnumeratedError):
+            checked_exc: EnumeratedError = PythonException(exc)
+        else:
+            checked_exc = exc
+        values["detail"] = checked_exc.message.strip()
+        values["errorCode"] = checked_exc.code.value.code
+
+        def _exc_to_meta(exc_val: EnumeratedError) -> Dict[str, Any]:
+            return {
+                "type": exc_val.detail.get("class", exc_val.__class__.__name__),
+                "code": exc_val.code.value.code,
+                "message": exc_val.message.strip(),
+                "detail": {k: v for k, v in exc_val.detail.items()},
+                "wrapping": [_exc_to_meta(wrapped) for wrapped in exc_val.wrapping],
+            }
+
+        values["meta"] = _exc_to_meta(checked_exc)
+        return cls(**values)
 
     def as_error(self, status_code: int) -> ApiError:
         """Serial this ErrorDetails as an ApiError from an ErrorResponse."""
@@ -121,12 +156,29 @@ class LegacyErrorResponse(BaseErrorBody):
         ...,
         description="A human-readable message describing the error.",
     )
+    errorCode: str = Field(
+        ..., description="The Opentrons error code associated with the error"
+    )
+
+    @classmethod
+    def from_exc(
+        cls: Type["LegacyErrorResponse"], exc: BaseException
+    ) -> "LegacyErrorResponse":
+        """Build a response from an exception, preserving some detail."""
+        if not isinstance(exc, EnumeratedError):
+            checked_exc: EnumeratedError = PythonException(exc)
+        else:
+            checked_exc = exc
+
+        return cls(
+            message=checked_exc.message.strip(), errorCode=checked_exc.code.value.code
+        )
 
 
 class ErrorBody(BaseErrorBody, GenericModel, Generic[ErrorDetailsT]):
     """A response body for a single error."""
 
-    errors: Tuple[ErrorDetailsT] = Field(..., description="Error details.")
+    errors: Sequence[ErrorDetailsT] = Field(..., description="Error details.")
     links: Optional[ResourceLinks] = Field(
         None,
         description=(

robot-server/robot_server/errors/exception_handlers.py

@@ -5,9 +5,10 @@
 from fastapi.responses import JSONResponse
 from fastapi.exceptions import RequestValidationError
 from starlette.exceptions import HTTPException as StarletteHTTPException
-from traceback import format_exception, format_exception_only
 from typing import Any, Callable, Coroutine, Dict, Optional, Sequence, Type, Union
 
+from opentrons_shared_data.errors import ErrorCodes, EnumeratedError, PythonException
+
 from robot_server.versioning import (
     API_VERSION,
     MIN_API_VERSION,
@@ -38,6 +39,18 @@
 log = getLogger(__name__)
 
 
+def _code_or_default(exc: BaseException) -> str:
+    if isinstance(exc, EnumeratedError):
+        # For a reason I cannot fathom, mypy thinks this is an Any.
+        # reveal_type(exc) # -> opentrons_shared_data.errors.exceptions.EnumeratedError
+        # reveal_type(exc.code) # -> opentrons_shared_data.errors.codes.ErrorCodes
+        # reveal_type(exc.code.value) # Any (????????????)
+        # This doesn't happen anywhere else or indeed in the else side of this clause.
+        return exc.code.value.code  # type: ignore [no-any-return]
+    else:
+        return ErrorCodes.GENERAL_ERROR.value.code
+
+
 def _route_is_legacy(request: Request) -> bool:
     """Check if router handling the request is a legacy v1 endpoint."""
     router = request.scope.get("router")
@@ -95,7 +108,9 @@ async def handle_framework_error(
 ) -> JSONResponse:
     """Map an HTTP exception from the framework to an API response."""
     if _route_is_legacy(request):
-        response: BaseErrorBody = LegacyErrorResponse(message=error.detail)
+        response: BaseErrorBody = LegacyErrorResponse(
+            message=error.detail, errorCode=ErrorCodes.GENERAL_ERROR.value.code
+        )
     else:
         response = BadRequest(detail=error.detail)
 
@@ -114,7 +129,9 @@ async def handle_validation_error(
             f"{'.'.join([str(v) for v in val_error['loc']])}: {val_error['msg']}"
             for val_error in validation_errors
         )
-        response: BaseErrorBody = LegacyErrorResponse(message=message)
+        response: BaseErrorBody = LegacyErrorResponse(
+            message=message, errorCode=ErrorCodes.GENERAL_ERROR.value.code
+        )
     else:
         response = MultiErrorResponse(
             errors=[
@@ -132,17 +149,19 @@ async def handle_validation_error(
     )
 
 
-async def handle_unexpected_error(request: Request, error: Exception) -> JSONResponse:
+async def handle_unexpected_error(
+    request: Request, error: BaseException
+) -> JSONResponse:
     """Map an unhandled Exception to an API response."""
-    detail = "".join(format_exception_only(type(error), error)).strip()
-    stacktrace = "".join(
-        format_exception(type(error), error, error.__traceback__, limit=-5)
-    ).strip()
+    if isinstance(error, EnumeratedError):
+        enumerated: EnumeratedError = error
+    else:
+        enumerated = PythonException(error)
 
     if _route_is_legacy(request):
-        response: BaseErrorBody = LegacyErrorResponse(message=detail)
+        response: BaseErrorBody = LegacyErrorResponse.from_exc(enumerated)
     else:
-        response = UnexpectedError(detail=detail, meta={"stacktrace": stacktrace})
+        response = UnexpectedError.from_exc(enumerated)
 
     return await handle_api_error(
         request,
@@ -154,15 +173,10 @@ async def handle_firmware_upgrade_required_error(
     request: Request, error: HWFirmwareUpdateRequired
 ) -> JSONResponse:
     """Map a FirmwareUpdateRequired error from hardware to an API response."""
-    detail = "".join(
-        format_exception(type(error), error, error.__traceback__, limit=0)
-    ).strip()
     if _route_is_legacy(request):
-        response: BaseErrorBody = LegacyErrorResponse(message=detail)
+        response: BaseErrorBody = LegacyErrorResponse.from_exc(error)
     else:
-        response = FirmwareUpdateRequired(
-            detail=detail, meta={"status_url": "/subsystems/status"}
-        )
+        response = FirmwareUpdateRequired.from_exc(error)
     return await handle_api_error(
         request, response.as_error(status.HTTP_503_SERVICE_UNAVAILABLE)
     )

robot-server/robot_server/errors/global_errors.py

@@ -1,39 +1,61 @@
 """Global error types."""
 from typing_extensions import Literal
+from typing import Type, Any
 
 from .error_responses import ErrorDetails
+from opentrons_shared_data.errors import ErrorCodes
 
 
 class UnexpectedError(ErrorDetails):
     """An error returned when an unhandled exception occurs."""
 
     id: Literal["UnexpectedError"] = "UnexpectedError"
     title: str = "Unexpected Internal Error"
+    errorCode: str = ErrorCodes.GENERAL_ERROR.value.code
 
 
 class BadRequest(ErrorDetails):
     """An error returned when the framework rejects the request."""
 
     id: Literal["BadRequest"] = "BadRequest"
     title: str = "Bad Request"
+    errorCode: str = ErrorCodes.GENERAL_ERROR.value.code
 
 
 class InvalidRequest(ErrorDetails):
     """An error returned when the request fails validation."""
 
     id: Literal["InvalidRequest"] = "InvalidRequest"
     title: str = "Invalid Request"
+    errorCode: str = ErrorCodes.GENERAL_ERROR.value.code
 
 
 class IDNotFound(ErrorDetails):
     """An error returned when an ID is specified incorrectly."""
 
     id: Literal["IDNotFound"] = "IDNotFound"
     title: str = "ID Not Found"
+    errorCode: str = ErrorCodes.GENERAL_ERROR.value.code
 
 
 class FirmwareUpdateRequired(ErrorDetails):
     """An error returned when a command requests to interact with hardware that requires an update."""
 
     id: Literal["FirmwareUpdateRequired"] = "FirmwareUpdateRequired"
     title: str = "Firmware Update Required"
+    errorCode: str = ErrorCodes.FIRMWARE_UPDATE_REQUIRED.value.code
+
+    @classmethod
+    def from_exc(
+        cls: Type["FirmwareUpdateRequired"],
+        exc: BaseException,
+        **supplemental_kwargs: Any
+    ) -> "FirmwareUpdateRequired":
+        """Build a FirmwareUpdateRequired from a specific exception. Preserves metadata."""
+        parent_inst = ErrorDetails.from_exc(exc, **supplemental_kwargs)
+        inst = FirmwareUpdateRequired(**parent_inst.dict())
+        if not inst.meta:
+            inst.meta = {"update_url": "/subsystems/update"}
+        else:
+            inst.meta["update_url"] = "/subsystems/update"
+        return inst

robot-server/robot_server/robot/calibration/errors.py

@@ -1,5 +1,6 @@
 from http import HTTPStatus
 
+from opentrons_shared_data.errors import ErrorCodes
 from robot_server.service.errors import ErrorDef, ErrorCreateDef
 
 
@@ -8,40 +9,48 @@ class CalibrationError(ErrorDef):
         status_code=HTTPStatus.FORBIDDEN,
         title="No Pipette Attached",
         format_string="No pipette present on {mount} mount",
+        error_code=ErrorCodes.PIPETTE_NOT_PRESENT.value.code,
     )
     NO_PIPETTE_ATTACHED = ErrorCreateDef(
         status_code=HTTPStatus.FORBIDDEN,
         title="No Pipette Attached",
         format_string="Cannot start {flow} with fewer than one pipette",
+        error_code=ErrorCodes.PIPETTE_NOT_PRESENT.value.code,
     )
     BAD_LABWARE_DEF = ErrorCreateDef(
         status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
         title="Bad Labware Definition",
         format_string="Bad definition for tip rack under calibration",
+        error_code=ErrorCodes.GENERAL_ERROR.value.code,
     )
     BAD_STATE_TRANSITION = ErrorCreateDef(
         status_code=HTTPStatus.CONFLICT,
         title="Illegal State Transition",
         format_string="The action {action} may not occur in the state {state}",
+        error_code=ErrorCodes.GENERAL_ERROR.value.code,
     )
     NO_STATE_TRANSITION = ErrorCreateDef(
         status_code=HTTPStatus.CONFLICT,
         title="No State Transition",
         format_string="No transition available for state {state}",
+        error_code=ErrorCodes.GENERAL_ERROR.value.code,
     )
     UNMET_STATE_TRANSITION_REQ = ErrorCreateDef(
         status_code=HTTPStatus.CONFLICT,
         title="Unmet State Transition Requirement",
         format_string="The command handler {handler} may not occur in the"
         ' state {state} when "{condition}" is not true',
+        error_code=ErrorCodes.GENERAL_ERROR.value.code,
     )
     UNCALIBRATED_ROBOT = ErrorCreateDef(
         status_code=HTTPStatus.CONFLICT,
         title="No Calibration Data Found",
         format_string="Cannot start {flow} without robot calibration",
+        error_code=ErrorCodes.GENERAL_ERROR.value.code,
     )
     ERROR_DURING_TRANSITION = ErrorCreateDef(
         status_code=HTTPStatus.INTERNAL_SERVER_ERROR,
         title="Error During State Transition",
         format_string="Event {action} failed to transition " "from {state}: {error}",
+        error_code=ErrorCodes.GENERAL_ERROR.value.code,
     )

robot-server/robot_server/runs/router/actions_router.py

@@ -116,12 +116,10 @@ async def create_run_action(
         )
 
     except RunActionNotAllowedError as e:
-        raise RunActionNotAllowed(detail=str(e)).as_error(
-            status.HTTP_409_CONFLICT
-        ) from e
+        raise RunActionNotAllowed.from_exc(e).as_error(status.HTTP_409_CONFLICT) from e
 
     except RunNotFoundError as e:
-        raise RunNotFound(detail=str(e)).as_error(status.HTTP_404_NOT_FOUND) from e
+        raise RunNotFound.from_exc(e).as_error(status.HTTP_404_NOT_FOUND) from e
 
     return await PydanticResponse.create(
         content=SimpleBody.construct(data=action),