Error Handling

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Wallet balance of 45.00 is less than the requested amount 100.00",
    "details": {
      "walletId": "wal_01J...",
      "balance": "45.00000000",
      "requested": "100.00"
    }
  }
}

import { WallgentError } from '@wallgent/sdk'

// Base class fields available on every error:
err.code        // string  — e.g. 'INSUFFICIENT_FUNDS'
err.message     // string  — human-readable description
err.statusCode  // number  — HTTP status code
err.details     // Record<string, unknown> | undefined

import Wallgent, {
  InsufficientFundsError,
  PolicyDeniedError,
  ApprovalRequiredError,
  RateLimitExceededError,
  WalletFrozenError,
  WallgentError,
} from '@wallgent/sdk'

const wg = new Wallgent({ apiKey: process.env.WALLGENT_API_KEY })

try {
  await wg.payments.send({
    from: 'wal_01J...',
    to: 'wal_01J...',
    amount: '50.00',
  })
} catch (err) {
  if (err instanceof InsufficientFundsError) {
    // Top up the wallet or reduce the amount
    console.error('Not enough balance:', err.details)
  } else if (err instanceof PolicyDeniedError) {
    // A spend policy blocked this payment — do not retry
    console.error('Policy blocked payment:', err.message)
  } else if (err instanceof ApprovalRequiredError) {
    // Not an error — payment is queued for human review (HTTP 202)
    const approvalId = err.details?.approvalId as string
    console.log('Awaiting approval:', approvalId)
  } else if (err instanceof WalletFrozenError) {
    // The wallet is frozen — contact your admin
    console.error('Wallet is frozen')
  } else if (err instanceof RateLimitExceededError) {
    // Retryable — wait and try again
    const retryAfter = err.details?.retryAfter as number ?? 60
    console.log(`Rate limited. Retry in ${retryAfter}s`)
  } else if (err instanceof WallgentError) {
    // Unknown Wallgent error — log and surface
    console.error(`Wallgent error ${err.code} (${err.statusCode}):`, err.message)
  } else {
    // Non-Wallgent error (network failure, etc.) — re-throw
    throw err
  }
}

import { ApprovalRequiredError } from '@wallgent/sdk'

try {
  const payment = await wg.payments.send({ ... })
  // HTTP 200 — payment posted immediately
} catch (err) {
  if (err instanceof ApprovalRequiredError) {
    // HTTP 202 — payment queued, do not retry
    const approvalId = err.details?.approvalId as string
    // Track the approval and wait for approval.approved or approval.rejected webhook
  }
}

const response = await fetch('https://api.wallgent.com/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ from: 'wal_01J...', to: 'wal_01J...', amount: '50.00' }),
})

if (!response.ok) {
  const body = await response.json()
  const { code, message, details } = body.error

  switch (code) {
    case 'INSUFFICIENT_FUNDS':
      // handle
      break
    case 'POLICY_DENIED':
      // handle
      break
    default:
      throw new Error(`Wallgent API error ${code}: ${message}`)
  }
}

const payment = await response.json()