Skip to content

Exceptions

bruno_llm.exceptions

Exception hierarchy for bruno-llm.

Defines custom exceptions for LLM provider errors, enabling consistent error handling across all providers.

LLMError

Bases: Exception

Base exception for all LLM-related errors.

All custom exceptions in bruno-llm inherit from this class.

Parameters:

Name Type Description Default
message str

Error message

 required
provider Optional[str]

Name of the provider that raised the error

 None
original_error Optional[Exception]

Original exception if available

 None
Source code in bruno_llm/exceptions.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
class LLMError(Exception):
    """
    Base exception for all LLM-related errors.

    All custom exceptions in bruno-llm inherit from this class.

    Args:
        message: Error message
        provider: Name of the provider that raised the error
        original_error: Original exception if available
    """

    def __init__(
        self,
        message: str,
        provider: Optional[str] = None,
        original_error: Optional[Exception] = None,
    ):
        self.message = message
        self.provider = provider
        self.original_error = original_error
        super().__init__(self.format_message())

    def format_message(self) -> str:
        """Format the error message with provider context."""
        parts = []
        if self.provider:
            parts.append(f"[{self.provider}]")
        parts.append(self.message)
        if self.original_error:
            parts.append(
                f"(caused by: {type(self.original_error).__name__}: {self.original_error})"
            )
        return " ".join(parts)

format_message()

Format the error message with provider context.

Source code in bruno_llm/exceptions.py 
34
35
36
37
38
39
40
41
42
43
44
def format_message(self) -> str:
    """Format the error message with provider context."""
    parts = []
    if self.provider:
        parts.append(f"[{self.provider}]")
    parts.append(self.message)
    if self.original_error:
        parts.append(
            f"(caused by: {type(self.original_error).__name__}: {self.original_error})"
        )
    return " ".join(parts)

AuthenticationError

Bases: LLMError

Raised when authentication with LLM provider fails.

Common causes: - Invalid API key - Expired API key - Missing API key - Invalid organization ID

Example

raise AuthenticationError("Invalid API key", provider="openai")

Source code in bruno_llm/exceptions.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
class AuthenticationError(LLMError):
    """
    Raised when authentication with LLM provider fails.

    Common causes:
    - Invalid API key
    - Expired API key
    - Missing API key
    - Invalid organization ID

    Example:
        >>> raise AuthenticationError("Invalid API key", provider="openai")
    """

    pass

RateLimitError

Bases: LLMError

Raised when API rate limits are exceeded.

Attributes:

Name Type Description
retry_after

Seconds to wait before retrying (if provided)
Example

raise RateLimitError("Rate limit exceeded", provider="openai", retry_after=60)

Source code in bruno_llm/exceptions.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
class RateLimitError(LLMError):
    """
    Raised when API rate limits are exceeded.

    Attributes:
        retry_after: Seconds to wait before retrying (if provided)

    Example:
        >>> raise RateLimitError("Rate limit exceeded", provider="openai", retry_after=60)
    """

    def __init__(
        self,
        message: str,
        provider: Optional[str] = None,
        original_error: Optional[Exception] = None,
        retry_after: Optional[int] = None,
    ):
        super().__init__(message, provider, original_error)
        self.retry_after = retry_after

ModelNotFoundError

Bases: LLMError

Raised when requested model is not found or not available.

Common causes: - Model name misspelled - Model not available in region - Model access not granted - Model has been deprecated

Example

raise ModelNotFoundError("Model 'gpt-5' not found", provider="openai")

Source code in bruno_llm/exceptions.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
class ModelNotFoundError(LLMError):
    """
    Raised when requested model is not found or not available.

    Common causes:
    - Model name misspelled
    - Model not available in region
    - Model access not granted
    - Model has been deprecated

    Example:
        >>> raise ModelNotFoundError("Model 'gpt-5' not found", provider="openai")
    """

    pass

ContextLengthExceededError

Bases: LLMError

Raised when input exceeds model's context length.

Attributes:

Name Type Description
max_tokens

Maximum tokens allowed
actual_tokens

Actual token count in request
Example

raise ContextLengthExceededError( ... "Context length exceeded", ... provider="openai", ... max_tokens=8192, ... actual_tokens=10000 ... )

Source code in bruno_llm/exceptions.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
class ContextLengthExceededError(LLMError):
    """
    Raised when input exceeds model's context length.

    Attributes:
        max_tokens: Maximum tokens allowed
        actual_tokens: Actual token count in request

    Example:
        >>> raise ContextLengthExceededError(
        ...     "Context length exceeded",
        ...     provider="openai",
        ...     max_tokens=8192,
        ...     actual_tokens=10000
        ... )
    """

    def __init__(
        self,
        message: str,
        provider: Optional[str] = None,
        original_error: Optional[Exception] = None,
        max_tokens: Optional[int] = None,
        actual_tokens: Optional[int] = None,
    ):
        super().__init__(message, provider, original_error)
        self.max_tokens = max_tokens
        self.actual_tokens = actual_tokens

StreamError

Bases: LLMError

Raised when streaming response encounters an error.

Common causes: - Network connection lost - Server-side error during streaming - Invalid chunk format - Stream interrupted

Example

raise StreamError("Stream connection lost", provider="openai")

Source code in bruno_llm/exceptions.py 
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
class StreamError(LLMError):
    """
    Raised when streaming response encounters an error.

    Common causes:
    - Network connection lost
    - Server-side error during streaming
    - Invalid chunk format
    - Stream interrupted

    Example:
        >>> raise StreamError("Stream connection lost", provider="openai")
    """

    pass

ConfigurationError

Bases: LLMError

Raised when provider configuration is invalid.

Common causes: - Missing required configuration - Invalid configuration values - Conflicting configuration options

Example

raise ConfigurationError("Missing base_url", provider="ollama")

Source code in bruno_llm/exceptions.py 
150
151
152
153
154
155
156
157
158
159
160
161
162
163
class ConfigurationError(LLMError):
    """
    Raised when provider configuration is invalid.

    Common causes:
    - Missing required configuration
    - Invalid configuration values
    - Conflicting configuration options

    Example:
        >>> raise ConfigurationError("Missing base_url", provider="ollama")
    """

    pass

TimeoutError

Bases: LLMError

Raised when request times out.

Attributes:

Name Type Description
timeout

Timeout value in seconds
Example

raise TimeoutError("Request timed out after 30s", provider="openai", timeout=30)

Source code in bruno_llm/exceptions.py 
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
class TimeoutError(LLMError):
    """
    Raised when request times out.

    Attributes:
        timeout: Timeout value in seconds

    Example:
        >>> raise TimeoutError("Request timed out after 30s", provider="openai", timeout=30)
    """

    def __init__(
        self,
        message: str,
        provider: Optional[str] = None,
        original_error: Optional[Exception] = None,
        timeout: Optional[float] = None,
    ):
        super().__init__(message, provider, original_error)
        self.timeout = timeout

InvalidResponseError

Bases: LLMError

Raised when provider returns invalid or unexpected response.

Common causes: - Malformed JSON response - Missing required fields - Unexpected response structure

Example

raise InvalidResponseError("Missing 'content' field", provider="openai")

Source code in bruno_llm/exceptions.py 
188
189
190
191
192
193
194
195
196
197
198
199
200
201
class InvalidResponseError(LLMError):
    """
    Raised when provider returns invalid or unexpected response.

    Common causes:
    - Malformed JSON response
    - Missing required fields
    - Unexpected response structure

    Example:
        >>> raise InvalidResponseError("Missing 'content' field", provider="openai")
    """

    pass

ProviderNotFoundError

Bases: LLMError

Raised when requested provider is not registered.

Example

raise ProviderNotFoundError("Provider 'unknown' not found")

Source code in bruno_llm/exceptions.py 
204
205
206
207
208
209
210
211
212
class ProviderNotFoundError(LLMError):
    """
    Raised when requested provider is not registered.

    Example:
        >>> raise ProviderNotFoundError("Provider 'unknown' not found")
    """

    pass