luplo.core.errors
=================

.. py:module:: luplo.core.errors

.. autoapi-nested-parse::

   Domain error hierarchy — one module for every caller-facing exception.

   Every error carries an ``http_status`` hint so the FastAPI layer can
   translate them with one mapping. CLI/MCP layers turn them into exit codes
   or text responses.

   Sibling modules (e.g. ``item_types``, ``tasks``, ``qa``) import the bases
   from here and raise specific subclasses, so callers can ``except
   errors.LuploDomainError`` once and catch them all.



Exceptions
----------

.. autoapisummary::

   luplo.core.errors.LuploDomainError
   luplo.core.errors.NotFoundError
   luplo.core.errors.ConflictError
   luplo.core.errors.ValidationError
   luplo.core.errors.AuthError
   luplo.core.errors.UnknownItemTypeError
   luplo.core.errors.ContextValidationError
   luplo.core.errors.TaskNotFoundError
   luplo.core.errors.TaskAlreadyInProgressError
   luplo.core.errors.TaskStateTransitionError
   luplo.core.errors.QACheckNotFoundError
   luplo.core.errors.QAStateTransitionError
   luplo.core.errors.GlossaryGroupHasActiveTermsError
   luplo.core.errors.WorkUnitHasActiveTasksError
   luplo.core.errors.IdTooShortError
   luplo.core.errors.InvalidIdFormatError
   luplo.core.errors.AmbiguousIdError


Module Contents
---------------

.. py:exception:: LuploDomainError(message: str)

   Bases: :py:obj:`Exception`


   Base class for all luplo domain errors. Carries an HTTP status hint.


   .. py:attribute:: http_status
      :type:  int
      :value: 400



   .. py:attribute:: message


.. py:exception:: NotFoundError(message: str)

   Bases: :py:obj:`LuploDomainError`


   Base class for all luplo domain errors. Carries an HTTP status hint.


   .. py:attribute:: http_status
      :type:  int
      :value: 404



.. py:exception:: ConflictError(message: str)

   Bases: :py:obj:`LuploDomainError`


   Base class for all luplo domain errors. Carries an HTTP status hint.


   .. py:attribute:: http_status
      :type:  int
      :value: 409



.. py:exception:: ValidationError(message: str)

   Bases: :py:obj:`LuploDomainError`


   Base class for all luplo domain errors. Carries an HTTP status hint.


   .. py:attribute:: http_status
      :type:  int
      :value: 400



.. py:exception:: AuthError(message: str)

   Bases: :py:obj:`LuploDomainError`


   Base class for all luplo domain errors. Carries an HTTP status hint.


   .. py:attribute:: http_status
      :type:  int
      :value: 401



.. py:exception:: UnknownItemTypeError(item_type: str)

   Bases: :py:obj:`ValidationError`


   Raised when create_item references an item_type not in the registry.


   .. py:attribute:: item_type


.. py:exception:: ContextValidationError(item_type: str, message: str)

   Bases: :py:obj:`ValidationError`


   Raised when items.context fails its registered JSON Schema.


   .. py:attribute:: item_type


.. py:exception:: TaskNotFoundError(task_id: str)

   Bases: :py:obj:`NotFoundError`


   Base class for all luplo domain errors. Carries an HTTP status hint.


   .. py:attribute:: task_id


.. py:exception:: TaskAlreadyInProgressError(work_unit_id: str, task_id: str)

   Bases: :py:obj:`ConflictError`


   Base class for all luplo domain errors. Carries an HTTP status hint.


   .. py:attribute:: work_unit_id


   .. py:attribute:: in_progress_task_id


.. py:exception:: TaskStateTransitionError(task_id: str, from_status: str, to_status: str)

   Bases: :py:obj:`ConflictError`


   Base class for all luplo domain errors. Carries an HTTP status hint.


   .. py:attribute:: task_id


   .. py:attribute:: from_status


   .. py:attribute:: to_status


.. py:exception:: QACheckNotFoundError(qa_id: str)

   Bases: :py:obj:`NotFoundError`


   Base class for all luplo domain errors. Carries an HTTP status hint.


   .. py:attribute:: qa_id


.. py:exception:: QAStateTransitionError(qa_id: str, from_status: str, to_status: str)

   Bases: :py:obj:`ConflictError`


   Base class for all luplo domain errors. Carries an HTTP status hint.


   .. py:attribute:: qa_id


   .. py:attribute:: from_status


   .. py:attribute:: to_status


.. py:exception:: GlossaryGroupHasActiveTermsError(group_id: str, term_id: str)

   Bases: :py:obj:`ConflictError`


   Raised when removing a canonical term while alias terms remain.

   Cascade-delete (option B) only fires when the canonical is the *last*
   active term in the group. If aliases remain the caller must promote
   one to canonical or remove them first.


   .. py:attribute:: group_id


   .. py:attribute:: term_id


.. py:exception:: WorkUnitHasActiveTasksError(work_unit_id: str, in_progress_task_id: str)

   Bases: :py:obj:`ConflictError`


   Base class for all luplo domain errors. Carries an HTTP status hint.


   .. py:attribute:: work_unit_id


   .. py:attribute:: in_progress_task_id


.. py:exception:: IdTooShortError(prefix: str, min_length: int)

   Bases: :py:obj:`ValidationError`


   Raised when a UUID prefix is shorter than the minimum length.


   .. py:attribute:: prefix


   .. py:attribute:: min_length


.. py:exception:: InvalidIdFormatError(value: str)

   Bases: :py:obj:`ValidationError`


   Raised when an ID is neither a full UUID nor a valid hex prefix.


   .. py:attribute:: value


.. py:exception:: AmbiguousIdError(prefix: str, matches: list[tuple[str, str]])

   Bases: :py:obj:`ConflictError`


   Raised when a UUID prefix matches more than one row.

   Carries up to two sample matches so callers can show the user enough
   to disambiguate without leaking the entire result set.


   .. py:attribute:: prefix


   .. py:attribute:: matches