API

Error Handling

Handle API errors gracefully in your Buff integration.

API Error Format

All Buff API endpoints return a consistent JSON format. On error:

error-response.json
typescript
1{
2  "ok": false,
3  "error": "Auth required. Use x-api-key OR x-wallet + x-signature headers."
4}

Common Errors

StatusErrorCause
401Auth requiredMissing API key or wallet signature
403Invalid API key / Invalid signatureWrong credentials
400txValueUsd is requiredMissing required field
400Invalid public key formatMalformed Solana address
400Simulation failedTransaction would fail on-chain
400Insufficient balance after rent exemptionNot enough SOL for swap
429Rate limitedToo many requests (60/min per IP)
500Transaction failedOn-chain execution error
502Jupiter quote failedJupiter API unavailable

Catching Errors

errors.ts
typescript
1import { Buff } from "buff-protocol-sdk"
2
3const buff = new Buff({ apiKey: "YOUR_KEY" })
4
5try {
6  const result = await buff.buildSwap(buffWalletPubkey)
7  if (result.ready) {
8    for (const tx of result.transactions) {
9      await buff.executeSwap(signedTx)
10    }
11  }
12} catch (err) {
13  if (err instanceof Error) {
14    // All SDK errors are plain Error instances
15    // The message contains the API error string
16    console.error("Buff error:", err.message)
17
18    // Common patterns:
19    if (err.message.includes("Auth required")) {
20      // Re-authenticate
21    }
22    if (err.message.includes("Rate limited")) {
23      // Back off and retry
24    }
25    if (err.message.includes("Jupiter")) {
26      // Jupiter API issue — retry later
27    }
28  }
29}

Retry Strategy

Transient failures (network, Jupiter, rate limits) can be retried:

retry.ts
typescript
1async function withRetry(fn, maxRetries = 3) {
2  for (let i = 0; i < maxRetries; i++) {
3    try {
4      return await fn()
5    } catch (err) {
6      if (i === maxRetries - 1) throw err
7      await new Promise(r => setTimeout(r, 1000 * (i + 1)))
8    }
9  }
10}
11
12// Usage
13const result = await withRetry(() => buff.buildSwap(wallet))
Note
The Buff API handles swap routing retries internally. Client-side retries are only needed for network-level failures (timeouts, connection drops, rate limits).