Scallop Error Handling

Error Handling

Understand and handle errors from the Scallop Python SDK.

Exception Hierarchy

ScallopError (base)
├── ScallopConfigError          — Configuration/setup issues
├── ScallopQueryError           — Read operation failures
│   └── ObligationNotFoundError — Obligation doesn't exist on-chain
├── ScallopTransactionError     — Transaction execution failures
│   ├── ObligationLockedError   — Obligation staked in borrow incentive
│   ├── InsufficientBalanceError— Not enough coins
│   ├── ZeroAmountError         — Amount must be > 0
│   └── LiquidationError        — Liquidation failures
│       └── NotLiquidatableError— Position is healthy
├── UnsupportedCoinError        — Unknown coin name/type
├── OraclePriceError            — Price feed failure
└── NetworkError                — RPC connection failures

All exceptions inherit from ScallopError, so you can catch broadly or narrowly.

Import and Basic Usage

# These are in the public API (importable from sui_scallop_sdk directly):
from sui_scallop_sdk import (
    ScallopError,
    ScallopConfigError,
    ScallopQueryError,
    ScallopTransactionError,
    ObligationNotFoundError,
    UnsupportedCoinError,
)

# These must be imported from the exceptions module directly:
from sui_scallop_sdk.exceptions import (
    ObligationLockedError,
    InsufficientBalanceError,
    ZeroAmountError,
    OraclePriceError,
    LiquidationError,
    NotLiquidatableError,
    NetworkError,
    parse_scallop_error,
)

Exception Details

ScallopError (Base)

class ScallopError(Exception):
    message: str
    code: int | None = None

All SDK exceptions carry a message and optional numeric code.

ScallopConfigError

Raised when SDK configuration is invalid.

try:
    config = ScallopConfig(network="invalid")
except ScallopConfigError as e:
    print(f"Config error: {e}")

ObligationNotFoundError

try:
    obligation = query.get_obligation("0xnonexistent")
except ObligationNotFoundError as e:
    print(f"Not found: {e.obligation_id}")

Fields: obligation_id: str

ObligationLockedError

Raised when an obligation is staked in the borrow incentive program and you try to modify it without unstaking first.

try:
    tx.withdraw_collateral_quick(amount, "sui", obligation_id, obligation_key)
except ObligationLockedError as e:
    print(f"Obligation {e.obligation_id} is locked (code: {e.code})")
    # Solution: unstake obligation first
    # tx.unstake_obligation(obligation_id, obligation_key)

Fields: obligation_id: str, code: int = 770

InsufficientBalanceError

try:
    tx.supply_quick(1_000_000_000_000, "sui", wallet_address)
except InsufficientBalanceError as e:
    print(f"Need {e.required} {e.coin_name}, have {e.available}")

Fields: coin_name: str, required: int, available: int

UnsupportedCoinError

try:
    tx.supply_quick(100, "unknown_coin", wallet_address)
except UnsupportedCoinError as e:
    print(f"Unsupported: {e.coin}")

Fields: coin: str (stored from the coin_name_or_type constructor arg)

ZeroAmountError

try:
    tx.supply_quick(0, "sui", wallet_address)
except ZeroAmountError as e:
    print(f"Zero amount for operation: {e.operation}")

Fields: operation: str, code: int = 1537

OraclePriceError

try:
    tx.update_asset_prices_quick(["sui"])
except OraclePriceError as e:
    print(f"Oracle error for {e.coin_name}: {e}")

Fields: coin_name: str, details: str | None

NotLiquidatableError

try:
    tx.liquidate_quick(obligation_id, amount, "usdc", "sui", wallet_address)
except NotLiquidatableError as e:
    print(f"Position healthy — risk: {e.risk_level:.4f}")

Fields: obligation_id: str, risk_level: float

NetworkError

try:
    client = ScallopClient(rpc_url="https://bad-rpc.example.com")
except NetworkError as e:
    print(f"Cannot connect: {e.message} (URL: {e.rpc_url})")

Fields: message: str, rpc_url: str | None

Parsing Raw Errors

The SDK provides parse_scallop_error() to convert raw error strings (from RPC responses) into typed exceptions:

from sui_scallop_sdk.exceptions import parse_scallop_error

raw_error = "MoveAbort(0x...::lending::770)"

parsed = parse_scallop_error(raw_error)
if isinstance(parsed, ObligationLockedError):
    print("Obligation is locked in borrow incentive!")

This is useful when catching generic transaction failures and wanting to provide specific recovery suggestions.

On-Chain Error Codes

The full error code reference is at Error Codes.

Error Handling Patterns

Broad Catch

try:
    result = builder.sign_and_send_tx_block(tx)
except ScallopError as e:
    print(f"Scallop error: {e}")
    if e.code:
        print(f"Error code: {e.code}")

Specific Recovery

from sui_scallop_sdk.exceptions import (
    InsufficientBalanceError,
    ObligationLockedError,
    OraclePriceError,
)

try:
    result = builder.sign_and_send_tx_block(tx)
except InsufficientBalanceError as e:
    print(f"Need more {e.coin_name}: have {e.available}, need {e.required}")
    # Maybe split the operation into smaller amounts
except ObligationLockedError:
    # Unstake, then retry
    tx2 = builder.create_tx_block()
    tx2.unstake_obligation(obligation_id, obligation_key)
    builder.sign_and_send_tx_block(tx2)
    # Now retry original operation
except OraclePriceError as e:
    print(f"Price feed down for {e.coin_name}, retrying...")
    # Maybe wait and retry, or use a different RPC
except ScallopError as e:
    print(f"Unexpected error: {e}")

Transaction with Full Error Handling

from sui_scallop_sdk import ScallopClient
from sui_scallop_sdk.exceptions import (
    ScallopError,
    InsufficientBalanceError,
    ObligationLockedError,
    OraclePriceError,
    NetworkError,
)

def safe_borrow(client, obligation_id, obligation_key, amount, coin_name):
    """Borrow with comprehensive error handling."""
    builder = client.create_builder()
    tx = builder.create_tx_block()

    try:
        borrowed = tx.borrow_quick(amount, coin_name, obligation_id, obligation_key)
        tx.transfer_objects([borrowed], client.wallet_address)
        result = builder.sign_and_send_tx_block(tx)

        if result.success:
            print(f"Borrowed {amount} {coin_name}: {result.digest}")
        else:
            print(f"TX failed: {result.error}")

        return result

    except InsufficientBalanceError as e:
        print(f"Insufficient balance: need {e.required}, have {e.available}")
    except ObligationLockedError:
        print("Obligation is locked — unstake from borrow incentive first")
    except OraclePriceError as e:
        print(f"Oracle unavailable for {e.coin_name}")
    except NetworkError as e:
        print(f"RPC error: {e.message}")
    except ScallopError as e:
        print(f"Error: {e}")

    return None

References

• Error Codes - Full error code reference
• Supported Coins - Valid coin names