---
title: "ADR-008: Error Handling Strategy"
manual: "TYPO3 LLM Extension"
version: "0.35"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:adr-008@0.35"
source: "Adr/Adr008ErrorHandlingStrategy.rst"
modified: "2026-09-16T22:09:16+00:00"
---

# ADR-008: Error Handling Strategy

-   *Status:* Accepted
-   *Date:* 2024-02
-   *Authors:* Netresearch DTT GmbH

## Context

LLM operations can fail due to:

-   Authentication issues.
-   Rate limiting.
-   Network errors.
-   Content filtering.
-   Invalid inputs.

## Decision

Implement **hierarchical exception system**:

**Exception hierarchy (Classes/Provider/Exception/ + Classes/Exception/)**

```text
\RuntimeException
├── Netresearch\NrLlm\Provider\Exception\ProviderException (base for provider errors)
│   ├── ProviderConnectionException (transport / network failure)
│   ├── ProviderResponseException (non-2xx / malformed API response)
│   ├── ProviderConfigurationException (missing/invalid provider setup)
│   ├── UnsupportedFeatureException (capability not implemented)
│   └── FallbackChainExhaustedException (all providers in the chain failed)
└── Netresearch\NrLlm\Exception\ConfigurationNotFoundException (missing configuration record)
\InvalidArgumentException
└── Netresearch\NrLlm\Exception\InvalidArgumentException (bad inputs)
```

Key features:

-   All provider errors extend `ProviderException` (itself a
    `RuntimeException`).
-   `FallbackChainExhaustedException` is raised by
    `FallbackMiddleware` when every provider in the chain fails
    ([ADR-021](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-021@0.35), [ADR-026](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-026@0.35)).
-   `ProviderResponseException` carries the offending HTTP status and a
    sanitised message (secrets stripped by `ErrorMessageSanitizerTrait`).
-   Exceptions include provider context.

## Consequences

**Positive:**

-   ●● Granular error handling.
-   ● Provider-specific recovery strategies.
-   ● Clear exception hierarchy.
-   ● Actionable error information.

**Negative:**

-   ◑ Many exception classes.
-   ◑ Exception handling complexity.
-   ✕ Breaking changes in new versions.

**Net Score:** +5.0 (Positive impact - robust error
handling enables graceful recovery strategies)