Handle Rate Limits

The SDK handles rate limits automatically out of the box. By default, when the server returns a 429 response, the SDK waits the Retry-After duration and retries up to 3 times. Monthly quota errors always throw immediately since retrying won’t help.

Default behavior

No configuration needed — rate limit retries work automatically:


import { BurnerClient } from '@burnandclaim/sdk'
 
const client = new BurnerClient({ apiKey: process.env.BURNER_API_KEY! })
 
// If this hits a rate limit, the SDK waits and retries automatically.
const assets = await client.getWalletAssets(walletAddress)

Observing SDK events

The events option lets you hook into the request lifecycle without writing retry logic. Use it for logging, metrics, alerting, or surfacing state in your UI:


const client = new BurnerClient({
  apiKey: process.env.BURNER_API_KEY!,
  events: {
    onRequest: ({ method, path }) => {
      metrics.increment('burner.request', { method, path })
    },
    onResponse: ({ method, path, status, durationMs }) => {
      metrics.histogram('burner.latency', durationMs, { method, path })
    },
    onRetry: ({ method, path, attempt, reason, delayMs }) => {
      metrics.increment('burner.retry', { method, path, reason })
    },
    onError: ({ method, path, status, error }) => {
      logger.warn('Burner API error', { method, path, status, error: error.message })
    },
  },
})

Custom rate limit decisions

The onRateLimit event controls retry behavior. Return true to auto-retry, false to throw immediately:


const client = new BurnerClient({
  apiKey: process.env.BURNER_API_KEY!,
  events: {
    onRateLimit: ({ retryAfter, attempt }) => {
      // Only retry twice, then give up
      return attempt <= 2
    },
  },
})

Disable auto-retry

Set autoRetryRateLimits: false to throw RateLimitError immediately on any 429:


import { BurnerClient, RateLimitError } from '@burnandclaim/sdk'
 
const client = new BurnerClient({
  apiKey: process.env.BURNER_API_KEY!,
  autoRetryRateLimits: false,
})
 
try {
  await client.getWalletAssets(walletAddress)
} catch (err) {
  if (err instanceof RateLimitError) {
    // Your own retry logic, queue system, etc.
  }
}

Monthly quota

When the monthly quota is exhausted, the SDK always throws QuotaExceededError. Use the onQuotaExceeded event for observability:


import { BurnerClient, QuotaExceededError } from '@burnandclaim/sdk'
 
const client = new BurnerClient({
  apiKey: process.env.BURNER_API_KEY!,
  events: {
    onQuotaExceeded: ({ quotaResetAt }) => {
      alertOps('Burn & Claim monthly quota exhausted', { quotaResetAt })
    },
  },
})

Batch to reduce request count

Minimize API calls by batching items in a single buildTransactions call:


// Build all items in one call instead of one per item:
const { transactions } = await client.buildTransactions(walletAddress, {
  items: items.map((item) => ({
    type: item.type,
    address: item.address,
    action: item.actions[0],
  })),
})

The server automatically splits items across multiple transactions if they exceed Solana’s per-transaction limits.