loom.core.errors

exception loom.core.errors.Conflict(message)[source]

Bases: DomainError

Raised when an operation conflicts with existing state.

Parameters:

message (str) – Description of the conflicting condition.

Return type:

None

exception loom.core.errors.DomainError(message, *, code)[source]

Bases: LoomError

Base class for all business-logic errors.

Raised inside UseCase execution. Transport adapters catch and convert these to their own error representations.

Parameters:
Return type:

None

exception loom.core.errors.Forbidden(message='Forbidden', *, reason=None, missing=())[source]

Bases: DomainError

Raised when an action is not permitted for the caller.

Parameters:

  • message (str) – Description of the access restriction.

  • reason (str | None) – Optional machine-readable cause a client can act on, such as "mfa_required". None when the refusal has no specific cause.

  • missing (Iterable[str]) – The permissions the caller lacks, in the order given; empty when the authorizer does not tell them.

Return type:

None

Both are keyword-only and public: the REST adapter puts them in the 403 body. Never put token claims, tenant data or anything the caller may not learn in them; leave them out where the refusal must not become an oracle for the policy.

Raises:

ValueError – If reason is not a non-blank string, missing is a single str or bytes, or an item of missing is not a non-blank string.

Parameters:

  • message (str)

  • reason (str | None)

  • missing (Iterable[str])

Return type:

None

exception loom.core.errors.LoomError(message, *, code)[source]

Bases: Exception

Base class for all framework errors.

Carries a machine-readable code used by transport adapters to produce appropriate responses (HTTP status, dead-letter routing, etc.) without coupling the domain to any transport layer.

Parameters:

  • message (str) – Human-readable description of the error.

  • code (str) – Machine-readable discriminator (e.g. "not_found").

Return type:

None

Example:

raise NotFound("User", id=42)
exception loom.core.errors.NotFound(entity, *, id)[source]

Bases: DomainError

Raised when a requested entity does not exist.

Emitted automatically by LoadStep when a repository returns None. May also be raised explicitly inside execute for semantic not-found conditions.

Parameters:

  • entity (str) – Name of the missing entity type (e.g. "User").

  • id (Any) – Lookup key that yielded no result.

Return type:

None

Example:

raise NotFound("User", id=42)
exception loom.core.errors.SystemError(message)[source]

Bases: LoomError

Base class for infrastructure and unexpected errors.

Raised when a repository, external service, or internal subsystem fails. Transport adapters may retry on SystemError and dead-letter on DomainError.

Parameters:

message (str) – Description of the system failure.

Return type:

None

exception loom.core.errors.Unauthenticated(message='Authentication required')[source]

Bases: DomainError

Raised when an action requires a verified caller and there is none.

Distinct from Forbidden: the caller can fix an Unauthenticated by presenting credentials, but cannot fix a Forbidden at all. Transport adapters map it to 401 with an authentication challenge.

Parameters:

message (str) – Description of the missing authentication.

Return type:

None

Example:

raise Unauthenticated("This endpoint requires an authenticated caller.")