Error handling

This section covers error handling and validation failure scenarios in the SDK.

---

LombardError

All SDK errors are instances of LombardError.

import { LombardError, isLombardError } from '@lombard.finance/sdk';

try {
  await stake.prepare({ amount: '0.0001', recipient: '0x...' });
} catch (error) {
  if (isLombardError(error)) {
    // error.code: string - Machine-readable error code
    // error.message: string - Human-readable message
    // error.metadata: object - Additional context
  }
}

---

Error Codes

General Errors

Code	Description
unknown-error	Unexpected error
invalid-configuration	Invalid SDK configuration
operation-timeout	Operation timed out
operation-cancelled	User cancelled operation

Provider Errors

Code	Description
provider-missing	Wallet provider not configured
provider-initialization-failed	Failed to initialize provider
provider-call-failed	Provider method call failed
signer-missing	Signer not available
user-rejected	User rejected transaction
network-mismatch	Wrong network selected

Validation Errors

Code	Description
invalid-address	Invalid address format
invalid-amount	Invalid amount format
amount-too-small	Amount below minimum
amount-too-large	Amount above maximum
insufficient-balance	Not enough balance
invalid-parameter	Invalid parameter value
missing-required-parameter	Required parameter missing
invalid-chain	Unsupported chain
invalid-state	Invalid action state

Contract Errors

Code	Description
contract-call-failed	Contract call failed
transaction-failed	Transaction failed
transaction-reverted	Transaction reverted
approval-failed	Token approval failed
insufficient-allowance	Token allowance too low
gas-estimation-failed	Gas estimation failed

---

Handling Specific Errors

import {
  LombardError,
  ValidationErrorCode,
  ProviderErrorCode,
  isLombardError,
} from '@lombard.finance/sdk';

try {
  await stake.authorize();
} catch (error) {
  if (!isLombardError(error)) {
    throw error;
  }

  switch (error.code) {
    case ProviderErrorCode.USER_REJECTED:
      // User cancelled - show retry option
      break;

    case ValidationErrorCode.AMOUNT_TOO_SMALL:
      // Amount too small - show minimum
      const min = error.metadata?.minimum;
      break;

    case ProviderErrorCode.NETWORK_MISMATCH:
      // Wrong network - prompt switch
      break;

    default:
      // Generic error handling
      break;
  }
}

---

Error Metadata

Errors include relevant context in the metadata property.

try {
  await stake.prepare({ amount: '0.0001', recipient: '0x...' });
} catch (error) {
  if (isLombardError(error) && error.code === 'amount-too-small') {
    // error.metadata.amount: '0.0001'
    // error.metadata.minimum: '0.001'
    // error.metadata.asset: 'BTC'
  }
}

---

Retry Pattern

Errors don't reset action state. Retry the failed step directly.