Exceptions

Provides custom exception classes, error handling and parsing utilities.

APIConnectionError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for when the client fails to connect to the model provider.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-API-CONNECTION.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

APITimeoutError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for when the request to the model provider times out.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-API-TIMEOUT.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

BaseInferenceError(message=None, *, debug_info=None, error=None)

Bases: BaseError

Base exception class for all gllm_inference errors.

Every concrete error exposes a stable code (GLLM-INF-<NAME>) that you can match on instead of parsing messages. Catch this class to handle any typed error raised by gllm_inference.

Attributes:

Name	Type	Description
code	str | None	Stable error code. Defined by each concrete subclass.
message	str	The error message.
debug_info	DebugInfo	Developer-only diagnostics, always with class_name. May include traceback, so do not expose it in API responses.
default_message	str | None	Default error message for the exception class.

Initialize the base inference error.

Parameters:

Name	Type	Description	Default
message	str | None	The error message. If None, uses the class's default_message. Defaults to None.	None
debug_info	DebugInfo | dict[str, Any] | None	Additional debug information for developers. Defaults to None.	None
error	Exception | None	The raw error that caused this one, recorded as error_type, original_message and traceback in debug_info. Defaults to None.	None

BaseInvokerError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInferenceError

Base exception class for all gllm_inference invoker errors.

Every concrete error exposes a stable code (GLLM-INF-<NAME>) that you can match on instead of parsing messages. Subclasses without their own code still work, log a warning, and fall back to a default code.

Attributes:

Name	Type	Description
code	str | None	Stable error code. Defined by each concrete subclass.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Developer-only diagnostics, always with class_name. May include traceback, so do not expose it in API responses.
default_message	str	Default error message for the exception class.
str_mode	ErrorStrMode | str	Whether str() and repr() return the full debug dump (VERBOSE, default) or only the clean message (MESSAGE).

Initialize the base exception.

Parameters:

Name	Type	Description	Default
*args	str | None	Positional arguments (deprecated). Use keyword arguments instead.	()
message	str	The error message. If empty, uses the class's default_message. Defaults to empty string.	''
class_name	str | None	The name of the class that raised the error. If None, auto-inferred from call stack. Defaults to None.	None
debug_info	DebugInfo | dict[str, Any] | None	Additional debug information for developers. Defaults to None.	None
error	Exception | None	The raw error. Defaults to None.	None

__init_subclass__(abstract=False, **kwargs)

Tolerantly validates and registers a subclass.

Lets you define custom invoker errors without a code: a warning is logged and a default code is used.

Parameters:

Name	Type	Description	Default
abstract	bool	Whether the subclass is an abstract base that is never raised directly. Defaults to False.	False
**kwargs	Any	Additional class keyword arguments passed to the parent.	{}

__repr__()

Return the error representation according to str_mode.

Returns:

Name	Type	Description
str	str	The verbose error message with debug information when str_mode is VERBOSE, otherwise ClassName('message').

__str__()

Return the error string according to str_mode.

Returns:

Name	Type	Description
str	str	The verbose error message with debug information when str_mode is VERBOSE, otherwise the clean message.

verbose()

Verbose error message with debug information.

Returns:

Name	Type	Description
str	str	The verbose error message with debug information.

ContextOverflowError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for when input size exceeds the model's context length limit.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-CONTEXT-OVERFLOW.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

ErrorStrMode

Bases: StrEnum

Defines what str() and repr() return for a BaseInvokerError.

Attributes:

Name	Type	Description
VERBOSE	str	Return the full debug dump, same as BaseInvokerError.verbose().
MESSAGE	str	Return only the clean message, without debug_info or the traceback.

FileOperationError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for file operation failures during model invocation.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-FILE-OPERATION.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

InferenceAttributeError(message=None, *, debug_info=None, error=None)

Bases: BaseInferenceError, AttributeError

Exception for attribute access on a gllm_inference component that is not available or not initialized.

Also a AttributeError, so existing except AttributeError handlers keep working.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-ATTRIBUTE.
message	str	The error message.
debug_info	DebugInfo	Developer-only diagnostics, always with class_name.
default_message	str	Default error message for the exception class.

InferenceFileNotFoundError(message=None, *, debug_info=None, error=None)

Bases: BaseInferenceError, FileNotFoundError

Exception for a file that a gllm_inference component expects but cannot find.

Also a FileNotFoundError, so existing except FileNotFoundError handlers keep working.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-FILE-NOT-FOUND.
message	str	The error message.
debug_info	DebugInfo	Developer-only diagnostics, always with class_name.
default_message	str	Default error message for the exception class.

InferenceNotImplementedError(message=None, *, debug_info=None, error=None)

Bases: BaseInferenceError, NotImplementedError

Exception for functionality that is not implemented or not supported by a gllm_inference component.

Also a NotImplementedError, so existing except NotImplementedError handlers keep working.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-NOT-IMPLEMENTED.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

InferenceOSError(message=None, *, debug_info=None, error=None)

Bases: BaseInferenceError, OSError

Exception for operating system, environment or resource-loading failures in gllm_inference components.

Also a OSError, so existing except OSError handlers keep working.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-OS.
message	str	The error message.
debug_info	DebugInfo	Developer-only diagnostics, always with class_name.
default_message	str	Default error message for the exception class.

InferenceRuntimeError(message=None, *, debug_info=None, error=None)

Bases: BaseInferenceError, RuntimeError

Exception for failures that occur at runtime inside gllm_inference components.

Also a RuntimeError, so existing except RuntimeError handlers keep working. Provider failures use InvokerRuntimeError (GLLM-INF-RUNTIME) instead.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-RUNTIME-ERR.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

InferenceTypeError(message=None, *, debug_info=None, error=None)

Bases: BaseInferenceError, TypeError

Exception for values of an unsupported type passed to gllm_inference components.

Also a TypeError, so existing except TypeError handlers keep working.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-TYPE.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

InferenceValueError(message=None, *, debug_info=None, error=None)

Bases: BaseInferenceError, ValueError

Exception for invalid values or configuration passed to gllm_inference components.

Also a ValueError, so existing except ValueError handlers keep working.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-VALIDATION.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

InvokerErrorTranslator(provider, class_name)

Translates raw provider exceptions into BaseInvokerError subclasses.

This translator is intended to be registered with gllm_core.retry.RetryConfig via the error_translators field so that provider-specific errors are normalized inside the retry loop.

Initialize the translator.

Parameters:

Name	Type	Description	Default
provider	ModelProvider	The model provider enum value.	required
class_name	str	The invoker class name for error context.	required

__call__(error)

Translate a raw exception into a BaseInvokerError subclass.

Parameters:

Name	Type	Description	Default
error	Exception	The raw provider error to translate.	required

Returns:

Name	Type	Description
Exception	Exception	The translated error (BaseInvokerError) or the original error if it is already a BaseInvokerError.

InvokerRuntimeError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for runtime errors that occur during the invocation of the model.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-RUNTIME.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

MissingOutputItemError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for missing required language model output item types.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-MISSING-OUTPUT-ITEM.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

ModelNotFoundError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for model not found errors.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-MODEL-NOT-FOUND.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

OperationUnsupportedError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError, NotImplementedError

Exception for unsupported operations across all operation types.

Applies to any operation type (file, skill, data store, etc.) when the operation is not supported or not implemented. Also a NotImplementedError, so existing except NotImplementedError handlers keep working.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-UNSUPPORTED-OPERATION.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

ProviderAuthError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for authorization failures due to API key issues.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-AUTH.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

no_organization(class_name=None, debug_info=None, error=None) classmethod

Factory for 'no organization' variant.

Parameters:

Name	Type	Description	Default
class_name	str | None	The name of the class that raised the error. If None, auto-inferred from call stack. Defaults to None.	None
debug_info	DebugInfo | dict[str, Any] | None	Additional debug information for developers. Defaults to None.	None
error	Exception | None	The raw error. Defaults to None.	None

Returns:

Name	Type	Description
ProviderAuthError	ProviderAuthError	An instance with a message indicating a missing organization.

ProviderBillingError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for provider account billing exhaustion.

Raised when the provider account cannot be billed for the request: prepaid credits are drained or a hard spend limit has been reached. This is distinct from ProviderRateLimitError, which covers transient rate limits and throughput quotas (e.g. tokens-per-minute allocations) that clear on their own. A billing exhaustion is not resolved by retrying or by falling back to another model on the same account; the account owner must update the billing details.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-BILLING.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

ProviderConflictError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for when the request to the model provider conflicts.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-CONFLICT.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

ProviderInternalError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for unexpected server-side errors.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-PROVIDER-INTERNAL.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

ProviderInvalidArgsError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for bad or malformed requests, invalid parameters or structure.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-INVALID-ARGS.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

ProviderOverloadedError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for when the engine is currently overloaded.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-OVERLOADED.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

ProviderRateLimitError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for rate limit violations.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-RATE-LIMIT.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

insufficient_quota(class_name=None, debug_info=None, error=None) classmethod

Factory for 'insufficient quota' variant.

Parameters:

Name	Type	Description	Default
class_name	str | None	The name of the class that raised the error. If None, auto-inferred from call stack. Defaults to None.	None
debug_info	DebugInfo | dict[str, Any] | None	Additional debug information for developers. Defaults to None.	None
error	Exception | None	The raw error. Defaults to None.	None

Returns:

Name	Type	Description
ProviderRateLimitError	ProviderRateLimitError	An instance with a message indicating exhausted quota/billing, as opposed to a transient rate limit that will clear on its own.

SkillOperationError(*args, message='', class_name=None, debug_info=None, error=None)

Bases: BaseInvokerError

Exception for skill operation failures.

Attributes:

Name	Type	Description
code	str	Stable error code, GLLM-INF-SKILL-OPERATION.
class_name	str	The name of the class that raised the error.
message	str	The error message.
debug_info	DebugInfo	Additional debug information for developers.
default_message	str	Default error message for the exception class.

__getattr__(name)

Lazily load the error extractor and translator to keep this package free of import cycles.

Parameters:

Name	Type	Description	Default
name	str	The attribute name being accessed.	required

Returns:

Name	Type	Description
Any	Any	The requested attribute.

Raises:

Type	Description
AttributeError	If the attribute is not a lazily loaded export.

get_all_provider_extractors()

Get all registered provider error extractor instances.

Returns:

Type	Description
list[BaseErrorExtractor]	list[BaseErrorExtractor]: List of all provider extractor instances.

get_error_extractor(provider)

Get the registered provider error extractor class.

Parameters:

Name	Type	Description	Default
provider	ModelProvider	The provider name.	required

Returns:

Type	Description
type[BaseErrorExtractor]	type[BaseErrorExtractor]: The registered provider error extractor class.