.. SPDX-License-Identifier: CC-BY-4.0
   SPDX-FileCopyrightText: Netresearch DTT GmbH

.. include:: /Includes.rst.txt

.. _api-exceptions:

==========
Exceptions
==========

.. php:namespace:: Netresearch\NrLlm\Exception

.. php:interface:: NrLlmExceptionInterface

   Marker interface implemented by errors generated by this extension
   on its public API surface — including the ``fromArray()``
   normalisation errors of ``ChatMessage`` / ``ToolSpec`` /
   ``ToolCall``. Catch this when an nr_llm-defined failure should take the
   same error path (:ref:`ADR-053 <adr-053>`)::

      try {
          $response = $this->llmManager->chatWithTools($messages, $tools);
      } catch (NrLlmExceptionInterface $e) {
          throw new MyDomainException($e->getMessage(), 0, $e);
      }

   This includes agent request validation, specialized service failures,
   delegated credential validation and internally generated runtime or
   configuration errors. Native parent catches remain compatible.
   Exceptions originating in a consumer callback or an external dependency
   are not automatically converted; PHP engine errors such as ``TypeError``
   are also outside this marker contract.
   For example, the bundled streaming adapters propagate their original
   PSR-18 network exception without an adapter retry loop. Callers can
   handle :php:`Psr\\Http\\Client\\NetworkExceptionInterface` separately;
   see :ref:`developer-streaming` for the fallback boundary.

   Tool-loop approval and input suspensions carry resumable state. Handle
   ``ToolApprovalRequiredException`` and ``ToolInputRequiredException``
   before a common marker catch when using the tool loop directly, so the
   suspension can be persisted and resumed.

.. php:class:: RuntimeException

   An internally generated runtime failure. Extends PHP's
   ``\RuntimeException`` and implements ``NrLlmExceptionInterface``.

.. php:class:: LogicException

   An internally generated logic or configuration error. Extends PHP's
   ``\LogicException`` and implements ``NrLlmExceptionInterface``.

.. php:namespace:: Netresearch\NrLlm\Provider\Exception

.. php:class:: ProviderException

   Base exception for provider errors.

   .. php:method:: getProvider(): string

      Get the provider that threw the exception.

.. php:class:: ProviderConfigurationException

   Thrown when a provider is incorrectly
   configured.

   Extends
   :php:class:`Netresearch\\NrLlm\\Provider\\Exception\\ProviderException`

.. php:class:: ProviderConnectionException

   Thrown when a connection to the provider
   fails.

   Extends
   :php:class:`Netresearch\\NrLlm\\Provider\\Exception\\ProviderException`

.. php:class:: ProviderResponseException

   Thrown when the provider returns an
   unexpected or error response.

   Extends
   :php:class:`Netresearch\\NrLlm\\Provider\\Exception\\ProviderException`

.. php:class:: UnsupportedFeatureException

   Thrown when a requested feature is not
   supported by the provider.

   Extends
   :php:class:`Netresearch\\NrLlm\\Provider\\Exception\\ProviderException`

.. php:namespace:: Netresearch\NrLlm\Exception

.. php:class:: InvalidArgumentException

   Thrown for invalid method arguments.

.. php:class:: ConfigurationNotFoundException

   Thrown when a named configuration is not found.

.. php:class:: ConfigurationInactiveException

   Thrown when a named configuration exists but is
   deactivated (:ref:`ADR-070 <adr-070>`).

   Only ``ConfigurationResolver::getActiveByIdentifier()`` differentiates
   inactive from not-found; the user-aware
   ``LlmConfigurationServiceInterface::getConfiguration()`` signals the
   inactive case as ``ConfigurationNotFoundException`` (code ``2690936773``).

.. _api-exceptions-planned-request-events:

Planned request events
======================

.. note::

   PSR-14 events (``BeforeRequestEvent``, ``AfterResponseEvent``) are planned
   for a future release. The event classes do not exist yet in the current
   codebase.

   The existing editorial write event is documented in :ref:`api-events`.