API

Error Handling

All SDK errors extend BuffError with structured context for debugging.

Error Types

ErrorWhenProperties
BuffPriceErrorPrice API fails or returns bad dataendpoint, statusCode
BuffSwapErrorJupiter quote/swap failsphase, statusCode, responseBody
BuffInsufficientBalanceErrorNot enough SOL for swaprequired, available
BuffNetworkErrorRPC connection failsrpcUrl
BuffWalletDerivationErrorInvalid or empty signature—

Catching Errors

errors.ts
typescript
1import {
2  BuffPriceError,
3  BuffSwapError,
4  BuffInsufficientBalanceError,
5  BuffWalletDerivationError,
6} from "@buff/sdk"
7
8try {
9  const { swap } = await buff.checkAndInvest()
10} catch (err) {
11  if (err instanceof BuffPriceError) {
12    // Price API down — retry later
13    console.error("Price API:", err.endpoint, err.statusCode)
14  }
15
16  if (err instanceof BuffSwapError) {
17    // Swap failed at a specific phase
18    console.error("Swap failed at:", err.phase)
19    // phase: "quote" | "transaction" | "send" | "confirm"
20  }
21
22  if (err instanceof BuffInsufficientBalanceError) {
23    // Not enough SOL
24    console.error("Need:", err.required, "Have:", err.available)
25  }
26}

Swap Retry Logic

The SDK automatically retries swap sends up to 2 times on transient failures. It also simulates the transaction before sending to catch errors early.

retry.ts
typescript
1// Built-in retry flow:
2// 1. Get Jupiter quote
3// 2. Get swap transaction
4// 3. Simulate transaction (catches most errors)
5// 4. Send → if fails, wait 1s → retry
6// 5. Send → if fails, wait 2s → retry
7// 6. If still fails → throw BuffSwapError

Event-Based Error Handling

Instead of try/catch, you can listen for error events:

events.ts
typescript
1buff.events.on("swapFailed", ({ error, asset, inputLamports }) => {
2  // Log to your error tracking
3  Sentry.captureException(error, {
4    extra: { asset, inputLamports }
5  })
6
7  // Show user-friendly message
8  showToast("Investment delayed — will retry on next transaction")
9})
Note
checkAndInvest() catches swap errors internally and emits swapFailed instead of throwing. This ensures your transaction flow isn't interrupted by swap failures.