Exceptions

Custom exception classes.

Exception Hierarchy

AgentError (base)
├── ConfigurationError
├── ModelBackendError
│   └── RateLimitError
├── ToolExecutionError
├── ContextOverflowError
├── MCPError
├── AuthenticationError
└── TimeoutError

Quick Example

from mamba_agents.errors import (
    AgentError,
    ModelBackendError,
    RateLimitError,
    AuthenticationError,
    ToolExecutionError,
    ContextOverflowError,
)

try:
    result = await agent.run(query)
except RateLimitError as e:
    print(f"Rate limited, retry after: {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
except ModelBackendError as e:
    print(f"Model error: {e}")
except ToolExecutionError as e:
    print(f"Tool {e.tool_name} failed: {e}")
except ContextOverflowError as e:
    print(f"Context overflow: {e.current_tokens}/{e.max_tokens} tokens")
except AgentError as e:
    print(f"Agent error: {e}")

API Reference

AgentError

AgentError(
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
)

Bases: Exception

Base exception for all agent errors.

All custom exceptions in this framework inherit from this class, allowing for easy catching of all agent-related errors.

ATTRIBUTE	DESCRIPTION
message	Human-readable error message.
cause	Original exception that caused this error.
details	Additional error context as key-value pairs.

Details can be accessed as attributes (e.g., error.config_key).

Initialize the error.

PARAMETER	DESCRIPTION
message	Human-readable error message. TYPE: str
cause	Original exception that caused this error. TYPE: Exception | None DEFAULT: None
**details	Additional error context. TYPE: Any DEFAULT: {}

Source code in src/mamba_agents/errors/exceptions.py

def __init__(
    self,
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
) -> None:
    """Initialize the error.

    Args:
        message: Human-readable error message.
        cause: Original exception that caused this error.
        **details: Additional error context.
    """
    super().__init__(message)
    self.message = message
    self.cause = cause
    self.details = details

ConfigurationError

ConfigurationError(
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
)

Bases: AgentError

Error in agent configuration.

Raised when configuration is invalid, missing required fields, or contains incompatible settings.

Attributes from details: config_key, expected, actual.

Source code in src/mamba_agents/errors/exceptions.py

def __init__(
    self,
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
) -> None:
    """Initialize the error.

    Args:
        message: Human-readable error message.
        cause: Original exception that caused this error.
        **details: Additional error context.
    """
    super().__init__(message)
    self.message = message
    self.cause = cause
    self.details = details

ModelBackendError

ModelBackendError(
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
)

Bases: AgentError

Error from the model backend.

Raised when the underlying model API returns an error, times out, or is unavailable.

Attributes from details: model, status_code, response_body, retryable (default: False).

Source code in src/mamba_agents/errors/exceptions.py

def __init__(
    self,
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
) -> None:
    """Initialize the error.

    Args:
        message: Human-readable error message.
        cause: Original exception that caused this error.
        **details: Additional error context.
    """
    super().__init__(message)
    self.message = message
    self.cause = cause
    self.details = details

RateLimitError

RateLimitError(message: str, **kwargs: Any)

Bases: ModelBackendError

Rate limit exceeded.

Raised when the model API rate limit is hit.

Attributes from details: retry_after.

Source code in src/mamba_agents/errors/exceptions.py

def __init__(self, message: str, **kwargs: Any) -> None:
    kwargs.setdefault("retryable", True)
    super().__init__(message, **kwargs)

AuthenticationError

AuthenticationError(
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
)

Bases: AgentError

Authentication failed.

Raised when API authentication fails, typically due to invalid or expired credentials.

Source code in src/mamba_agents/errors/exceptions.py

def __init__(
    self,
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
) -> None:
    """Initialize the error.

    Args:
        message: Human-readable error message.
        cause: Original exception that caused this error.
        **details: Additional error context.
    """
    super().__init__(message)
    self.message = message
    self.cause = cause
    self.details = details

ToolExecutionError

ToolExecutionError(
    message: str,
    *,
    tool_name: str | None = None,
    tool_args: dict[str, Any] | None = None,
    **kwargs: Any,
)

Bases: AgentError

Error during tool execution.

Raised when a tool fails to execute properly, either due to invalid arguments, permission issues, or runtime errors.

Attributes from details: tool_name, tool_args.

Source code in src/mamba_agents/errors/exceptions.py

def __init__(
    self,
    message: str,
    *,
    tool_name: str | None = None,
    tool_args: dict[str, Any] | None = None,
    **kwargs: Any,
) -> None:
    # Redact sensitive values in tool_args
    if tool_args:
        tool_args = {
            k: "[REDACTED]" if "key" in k.lower() or "secret" in k.lower() else v
            for k, v in tool_args.items()
        }
    super().__init__(message, tool_name=tool_name, tool_args=tool_args, **kwargs)

ContextOverflowError

ContextOverflowError(
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
)

Bases: AgentError

Context window exceeded.

Raised when the conversation context exceeds the model's maximum context window and cannot be compacted further.

Attributes from details: current_tokens, max_tokens, compaction_attempted (default: False).

Source code in src/mamba_agents/errors/exceptions.py

def __init__(
    self,
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
) -> None:
    """Initialize the error.

    Args:
        message: Human-readable error message.
        cause: Original exception that caused this error.
        **details: Additional error context.
    """
    super().__init__(message)
    self.message = message
    self.cause = cause
    self.details = details

MCPError

MCPError(
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
)

Bases: AgentError

Error from MCP server interaction.

Raised when communication with an MCP server fails, the server returns an error, or authentication fails.

Attributes from details: server_name, server_url.

Source code in src/mamba_agents/errors/exceptions.py

def __init__(
    self,
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
) -> None:
    """Initialize the error.

    Args:
        message: Human-readable error message.
        cause: Original exception that caused this error.
        **details: Additional error context.
    """
    super().__init__(message)
    self.message = message
    self.cause = cause
    self.details = details

TimeoutError

TimeoutError(
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
)

Bases: AgentError

Operation timed out.

Raised when an operation exceeds its timeout limit.

Attributes from details: timeout_seconds, operation.

Source code in src/mamba_agents/errors/exceptions.py

def __init__(
    self,
    message: str,
    *,
    cause: Exception | None = None,
    **details: Any,
) -> None:
    """Initialize the error.

    Args:
        message: Human-readable error message.
        cause: Original exception that caused this error.
        **details: Additional error context.
    """
    super().__init__(message)
    self.message = message
    self.cause = cause
    self.details = details