ADR-008: Error Handling Strategy 

Status 

Accepted (2024-02)

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/) 
\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)
Copied!

Key features:

  • All provider errors extend ProviderException (itself a RuntimeException).
  • FallbackChainExhaustedException is raised by FallbackMiddleware when every provider in the chain fails (ADR-021, ADR-026).
  • 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)