Errors

All PyMediate-specific exceptions subclass PyMediateError. They split into definition-time errors (raised at import, when a class is defined — fatal programming mistakes, not meant to be caught) and dispatch-time errors (raised while routing a request — catchable). See the error handling guide for how to treat each group.

PyMediateError

from pymediate import PyMediateError

class PyMediateError(Exception):
    def __init__(self, message: str, docs_path: str | None = None): ...

Base exception for all PyMediate errors. Carries an optional docs_path pointing to the relevant documentation page, which subclasses use to append a "learn more" link to their messages.

Definition-time errors

Raised by Handler.__init_subclass__ validation the moment a class is defined — the failing import is the signal. Fix the code; don't catch these.

InvalidHandlerSignatureError

class InvalidHandlerSignatureError(PyMediateError):
    def __init__(self, handler_type: type, issue: str): ...

The handler's __call__ has the wrong shape: missing type annotations, wrong parameter count, a parameter type that doesn't match Handler[RequestT], or sync/async mismatch (an async def __call__ on a sync Handler, or vice versa).

InvalidRequestTypeError

class InvalidRequestTypeError(PyMediateError):
    def __init__(self, request_type: type): ...

A handler was parameterized on a type that doesn't inherit from Request[ResponseType].

ResponseTypeMismatchError

class ResponseTypeMismatchError(PyMediateError):
    def __init__(self, handler_type: type, expected_type: type, actual_type: type): ...

The handler's return annotation disagrees with the response type its request declares. Note this is runtime (import-time) validation — mypy doesn't catch this particular mismatch. See type safety.

HandlerAlreadyRegisteredError

class HandlerAlreadyRegisteredError(PyMediateError):
    def __init__(
        self,
        request_type: type,
        existing_handler: type,
        new_handler: type,
        existing_location: str | None = None,
    ): ...

A second Handler subclass was defined for a request type that already has one. PyMediate enforces one handler per request type, process-wide. The message includes both handler names and, when available, the file and line where the first was registered. Common in test suites — see testing.

Dispatch-time errors

Raised while a request is being routed. Both usually indicate a misconfigured deployment (something was never registered) rather than bad client input — at a web edge they map to a 500, not a 4xx.

HandlerNotFoundError

class HandlerNotFoundError(PyMediateError):
    def __init__(self, request_type: type, available_handlers: list[type] | None = None): ...

mediator.send() received a request whose type has no registered handler. The message lists the handlers that are available.

from pymediate import HandlerNotFoundError

try:
    response = mediator.send(GetUserRequest(user_id=1))
except HandlerNotFoundError:
    logger.error("Handler missing from services — config bug")
    raise

ServiceNotFoundError

class ServiceNotFoundError(Exception):
    def __init__(self, service_type: type, available_types: list[type]) -> None: ...

A ServiceProvider.get() call couldn't resolve the requested type. Lives in pymediate.service and — unlike the others — subclasses plain Exception, not PyMediateError.