Exceptions

All exceptions inherit from MultiRunError. Import from multirun.exceptions or top-level multirun.

from multirun import MultiRunError, BudgetExceededError, StepError

MultiRunError

Base exception for all MultiRun errors.

class MultiRunError(Exception):
    message: str
    run_id: str | None

BudgetExceededError

Raised when a run exceeds its budget constraints (tokens, cost, or steps).

class BudgetExceededError(MultiRunError):
    budget_type: str | None   # "tokens", "cost", "steps"
    limit: float | None       # the configured limit
    used: float | None        # the amount consumed

Raised by the @step decorator when check_budget=True (default) and the run's budget is exceeded before step execution.

CheckpointError

Raised when checkpoint save or load fails.

class CheckpointError(MultiRunError):
    checkpoint_id: str | None
    operation: str | None      # "save", "load", "serialize", "deserialize"

ReplayError

Raised when replay operations fail (e.g. corrupted checkpoint state).

class ReplayError(MultiRunError):
    step_id: str | None
    reason: str | None         # "input_mismatch", "missing_checkpoint", "corrupted_state"

AuthenticationError

Raised when API key authentication fails (invalid, expired, or missing key).

class AuthenticationError(MultiRunError):
    error_code: str | None
    status_code: int | None

TransportError

Raised when the transport layer fails (HTTP errors, connection issues).

class TransportError(MultiRunError):
    status_code: int | None
    endpoint: str | None

PolicyViolationError

Raised when a policy rule is violated.

class PolicyViolationError(MultiRunError):
    policy_rule: str | None
    action: str | None         # "rejected", "rate_limited", "circuit_open"

StepError

Raised when a step fails after exhausting all retry attempts.

class StepError(MultiRunError):
    step_id: str | None
    step_name: str | None
    attempt: int               # final attempt number
    max_attempts: int
    original_error: Exception | None

Error handling patterns

from multirun import BudgetExceededError, StepError, TransportError

try:
    result = await my_agent("query")
except BudgetExceededError as e:
    print(f"Budget exceeded: {e.budget_type} — used {e.used}/{e.limit}")
except StepError as e:
    print(f"Step '{e.step_name}' failed after {e.max_attempts} attempts")
    print(f"Original error: {e.original_error}")
except TransportError as e:
    print(f"Transport error (HTTP {e.status_code}): {e.message}")

Exceptions

On this page