snoozeml.exceptions — Exception Hierarchy & Error Mappers#

Domain exception hierarchy and HTTP/gRPC error mapping for SnoozeML.

Maintains strict parity with SnoozeML’s Rust InferenceError variants across both HTTP REST (src/server/http.rs) and Tonic gRPC (src/server/grpc/convert.rs).

exception snoozeml.exceptions.SnoozeError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: Exception

Base exception for all SnoozeML client, server, and conversion errors.

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

message#

Human-readable explanation of the error.

status_code#

Optional HTTP status code (e.g. 404, 503).

grpc_code#

Optional gRPC status code name (e.g. "NOT_FOUND").

retry_after#

Optional server-suggested retry delay in seconds.

model_id#

Optional identifier of the target model associated with the failure.

exception snoozeml.exceptions.ModelNotFoundError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: SnoozeError

Raised when a requested model_id is not registered (HTTP 404 / gRPC NOT_FOUND).

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

exception snoozeml.exceptions.InvalidInputError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: SnoozeError

Raised when input tensors have invalid shapes, dtypes, or element counts (HTTP 400 / gRPC INVALID_ARGUMENT).

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

exception snoozeml.exceptions.ShapeMismatchError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: InvalidInputError

Raised when tensor dimensions are incompatible during batch collation or forward pass (HTTP 400 / gRPC INVALID_ARGUMENT).

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

exception snoozeml.exceptions.InferenceTimeoutError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: SnoozeError

Raised when a request exceeds its processing or queue deadline (HTTP 504 / gRPC DEADLINE_EXCEEDED).

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

exception snoozeml.exceptions.ModelLoadingError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: SnoozeError

Raised when model weights are currently being loaded (HTTP 503 / gRPC UNAVAILABLE).

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

exception snoozeml.exceptions.ResourceExhaustedError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: SnoozeError

Raised when server memory or queue capacity is exhausted (HTTP 503 / gRPC RESOURCE_EXHAUSTED).

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

exception snoozeml.exceptions.OutOfMemoryError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: ResourceExhaustedError

Raised when device VRAM or host RAM allocation fails (HTTP 503 / gRPC RESOURCE_EXHAUSTED).

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

exception snoozeml.exceptions.UnsupportedArchitectureError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: SnoozeError

Raised when a Safetensors model architecture is unsupported natively (HTTP 501 / gRPC UNIMPLEMENTED).

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

exception snoozeml.exceptions.AuthenticationError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: SnoozeError

Raised when authentication credentials are missing or invalid (HTTP 401 / gRPC UNAUTHENTICATED).

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

exception snoozeml.exceptions.PermissionDeniedError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: SnoozeError

Raised when the authenticated identity lacks the required RBAC role (HTTP 403 / gRPC PERMISSION_DENIED).

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

exception snoozeml.exceptions.SnoozeConnectionError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: SnoozeError

Raised when the SnoozeML daemon cannot be reached over HTTP or gRPC.

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

exception snoozeml.exceptions.RuntimeInferenceError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: SnoozeError

Raised when an internal engine or runtime error occurs (HTTP 500 / gRPC INTERNAL).

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

exception snoozeml.exceptions.ConversionError(message, *, status_code=None, grpc_code=None, retry_after=None, model_id=None)[source]#

Bases: SnoozeError

Raised when exporting a scikit-learn, PyTorch, or XGBoost model fails.

Parameters:

  • message (str)

  • status_code (Optional[int])

  • grpc_code (Optional[str])

  • retry_after (Optional[int])

  • model_id (Optional[str])

Return type:

None

snoozeml.exceptions.map_http_error(status_code, body_text, headers=None, model_id=None)[source]#

Maps an HTTP error response from SnoozeML to the corresponding SnoozeError subclass.

Parameters:

  • status_code (int) – HTTP status code returned by the server.

  • body_text (str) – Raw response body text or JSON string.

  • headers (Mapping[str, str] | None) – Optional response headers dictionary.

  • model_id (str | None) – Optional model identifier involved in the request.

Returns:

A specific SnoozeError subclass matching the failure mode.

Return type:

SnoozeError

snoozeml.exceptions.map_grpc_error(rpc_error, model_id=None)[source]#

Maps a grpc.RpcError from SnoozeML to the canonical SnoozeError subclass.

Parameters:

  • rpc_error (Any) – The gRPC exception raised by grpcio.

  • model_id (str | None) – Optional model identifier involved in the RPC.

Returns:

A specific SnoozeError subclass matching the gRPC status code.

Return type:

SnoozeError