# How to Handle LLMError and Provider-Specific Exceptions in aisuite

> Unified LLMError exception in aisuite simplifies error handling. Catch any LLM failure with one handler and access original SDK exceptions via __cause__ for provider-specific logic.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: how-to-guide
- Published: 2026-07-28

---

**All provider errors in aisuite are unified under the `LLMError` exception class, allowing you to catch any LLM failure with a single handler while still accessing the original SDK exception through the `__cause__` attribute for provider-specific logic.**

When building applications with the `andrewyng/aisuite` library, you need a robust strategy to handle failures from multiple LLM backends. The framework abstracts OpenAI, Anthropic, and other providers behind a unified interface, and this abstraction extends to error handling through custom exception types defined in the core provider module.

## The Unified Exception Model

aisuite defines a provider-agnostic error architecture in **[[`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py)](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py)**. The abstract `Provider` class declares two primary exception types that all concrete implementations use:

- **`LLMError`** – Raised whenever a provider encounters a problem during chat completion requests (synchronous, asynchronous, or streaming).
- **`ASRError`** – Raised for audio transcription-related failures.

This design ensures that application code can handle errors from any provider without importing multiple SDK-specific exception classes.

## How Providers Wrap SDK Exceptions

Each concrete provider implementation wraps low-level SDK exceptions into the unified `LLMError` type before propagating them. This preserves the original exception chain while presenting a consistent surface API.

In **[[`aisuite/providers/openai_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/openai_provider.py)](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/openai_provider.py)** and similar provider files, you will find this pattern:

```python
try:
    # Call the underlying SDK

    response = openai.ChatCompletion.create(...)
except Exception as e:  # catches any provider-specific error

    raise LLMError(f"An error occurred: {e}") from e

```

The `raise ... from e` syntax preserves the original exception as the cause, making it accessible via the `__cause__` attribute for debugging or provider-specific handling.

## Catching and Handling LLMError

Because `LLMError` is the public exception type, your application code should catch it to handle any LLM-related failure generically.

### Basic Error Handling

Import `LLMError` from the provider module and wrap your client calls:

```python
from aisuite.client import AISuiteClient
from aisuite.provider import LLMError

client = AISuiteClient(provider="openai", config={...})

try:
    response = client.chat(model="gpt-4o", messages=[{"role": "user", "content": "Hello"}])
    print(response.content)
except LLMError as e:
    # Generic handling (e.g., retry, fallback)

    print(f"LLM failed: {e}")

```

### Inspecting Provider-Specific Errors

If you need to react to a specific provider's error (e.g., rate limits, authentication failures), inspect the underlying cause via the exception's `__cause__` attribute:

```python
import openai
from aisuite.provider import LLMError

try:
    reply = client.chat(model="gpt-4o", messages=msgs)
except LLMError as err:
    if isinstance(err.__cause__, openai.error.RateLimitError):
        # Exponential back-off or switch provider

        handle_rate_limit()
    elif isinstance(err.__cause__, anthropic.exceptions.AnthropicError):
        # Anthropic-specific logic

        handle_anthropic_issue()
    else:
        # Fallback for other errors

        fallback()

```

This approach maintains the abstraction boundary while giving you access to SDK-specific error properties when necessary.

## Handling Streaming and ASR Exceptions

The unified exception model applies to streaming and audio transcription workflows as well.

### Streaming Errors

When using streaming APIs, the abstract `Provider` class in **[[`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py)](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py#L54-L56)** raises `LLMError` if a provider does not implement `chat_completions_create_stream`:

```python
from aisuite.provider import LLMError

try:
    async for chunk in client.achat_stream(model="gpt-4o", messages=msgs):
        print(chunk.delta.content, end="")
except LLMError as e:
    # Provider does not support streaming; revert to non-streaming call

    response = client.chat(model="gpt-4o", messages=msgs)
    print(response.content)

```

### Audio Transcription Errors

For ASR calls, catch `ASRError` to handle transcription failures:

```python
from aisuite.provider import ASRError

try:
    transcription = client.transcribe_audio("audio.wav")
except ASRError as e:
    print(f"Audio transcription failed: {e}")

```

## Implementation Reference

These key source files demonstrate the error handling implementation:

- **[[`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py)](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py)** – Defines `Provider`, `LLMError`, `ASRError`, and the baseline streaming implementation.
- **[[`aisuite/providers/openai_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/openai_provider.py)](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/openai_provider.py)** – Concrete OpenAI provider demonstrating SDK error wrapping.
- **[[`aisuite/providers/anthropic_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/anthropic_provider.py)](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/anthropic_provider.py)** – Anthropic provider with its own error mapping logic.
- **[[`aisuite/client.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/client.py)](https://github.com/andrewyng/aisuite/blob/main/aisuite/client.py)** – Public client façade that propagates exceptions to callers.
- **[[`aisuite/framework/provider_interface.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/provider_interface.py)](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/provider_interface.py)** – Internal interface ensuring providers follow the error contract.

## Summary

- **Unified error type**: `LLMError` (and `ASRError` for audio) provides a consistent exception interface across all providers.
- **Exception chaining**: Provider-specific SDK errors are wrapped using `raise LLMError(...) from e`, preserving the original exception in `__cause__`.
- **Stream support detection**: The default `Provider.chat_completions_create_stream` raises `LLMError` when streaming is not implemented.
- **Granular control**: Inspect `err.__cause__` to access underlying SDK exceptions for provider-specific error handling.
- **Async compatibility**: The error model applies identically to both synchronous and asynchronous client calls.

## Frequently Asked Questions

### What is the difference between LLMError and ASRError in aisuite?

`LLMError` handles failures from chat completion requests across all text-based models, while `ASRError` specifically handles audio transcription failures. Both are defined in [`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py) and follow the same wrapping pattern, but they target different functionality domains within the library.

### How do I access the original provider error after catching LLMError?

Access the original SDK exception through the `__cause__` attribute of the caught `LLMError` instance. For example, `isinstance(err.__cause__, openai.error.RateLimitError)` lets you detect OpenAI-specific rate limits while maintaining the unified exception interface.

### Why does aisuite raise LLMError when using streaming with some providers?

The abstract `Provider` class defines `chat_completions_create_stream` to raise `LLMError` by default. Concrete providers must override this method to support streaming; if they do not, the base implementation raises `LLMError` to signal that streaming is unavailable for that backend.

### Can I catch provider-specific errors like RateLimitError directly in aisuite?

No, aisuite intentionally wraps all provider-specific exceptions into `LLMError` to maintain abstraction. You should catch `LLMError` and inspect `err.__cause__` to handle provider-specific cases, ensuring your error handling logic remains compatible when switching between providers.