Skip to main content
Typed error codes and the unified SDK exception. The SDK raises a single exception type, BioptimusError, tagged with a machine-readable ErrorCode. Low-level code raises the typed error with structured context; this module owns the actionable remediation text for each code. The system boundary (for example the per-slide handler) logs it once with the attached code, so whoever reads the log gets an instant explanation and a direct fix. Each ErrorCode member carries two pieces of information:
  • its value is the stable, dotted support code (for example "BIO-WSI-001") used in logs, dashboards, and customer communication; and
  • its name maps to a human-readable event slug (for example "wsi_backend_unavailable") via ErrorCode.event.

​
ErrorCode

Stable, machine-readable error codes for SDK failures. The member value is the dotted support code embedded in logs and shared with customers. The member name doubles as a structured-log event slug through event.

​
event

Returns the structured-log event slug for this code. Returns: The lowercased member name, for example "wsi_backend_unavailable".

​
remediation

Returns the central remediation hint for this code, if one exists.

​
remediation_for

Returns the central remediation hint for an error code.
​
An ErrorCode member or its string value.
Returns: The remediation string when the code is known, otherwise None.

​
BioptimusError

Unified, typed exception raised across the SDK. Wraps a machine-readable ErrorCode together with structured diagnostic context and an actionable remediation hint. It is designed to be raised at low levels (raise BioptimusError(...) from exc) and logged exactly once at a system boundary.

​
to_dict

Returns the structured representation for logging or serialization. Returns: A mapping with the error code, event slug, message, context, and remediation, suitable for inclusion in a structured log record.

​
BioptimusValueError

A BioptimusError that is also a ValueError. Raised where the SDK historically raised a plain ValueError (for example an unsupported format or invalid input). Inheriting from both keeps existing except ValueError handlers working while exposing the typed code, context, and remediation.

​
BioptimusRuntimeError

A BioptimusError that is also a RuntimeError. Raised where the SDK historically raised a plain RuntimeError (for example an unavailable backend or a failed operation). Inheriting from both keeps existing except RuntimeError handlers working while exposing the typed code, context, and remediation.

​
BioptimusImportError

A BioptimusError that is also an ImportError. Raised when a feature needs an optional dependency shipped as a bioptimus-sdk extra (for example bioptimus-sdk[torch]) that is not installed. Inheriting from both keeps existing except ImportError handlers working while exposing the typed code, context, and remediation that name the missing extra and the exact install command.

​
wrap_as

Translates an unexpected exception in the block into a typed error. Centralizes the recurring “wrap a low-level failure as a typed error” boundary: an already-typed BioptimusError propagates unchanged, while any other exception is re-raised as error_cls with code, message, and context augmented with the original exception’s type and detail. This mirrors bioptimus.observability.fsboundary.fs_read, but for arbitrary operations rather than filesystem reads.
​
The ErrorCode to tag the wrapped failure with.
​
The human-readable message for the wrapped error.
​
The typed error class to raise. Defaults to BioptimusRuntimeError; pass BioptimusValueError for input-validation failures.
​
Structured context fields recorded on the wrapped error, in addition to the automatically added error_type and detail.
Returns: A context manager that re-raises unexpected exceptions as error_cls.