Errors

The Burn & Claim API returns structured error responses. The SDK surfaces these as HTTP errors from the underlying ky client.

Error response shape

All error responses follow this format:


interface ApiError {
  statusCode: number
  message: string
  error?: string  // HTTP status text (e.g., "Bad Request", "Unauthorized")
}

Validation errors (400)

Validation errors include field-level detail in the message:


{
  "statusCode": 400,
  "message": "items must contain at least 1 element",
  "error": "Bad Request"
}

Authentication errors (401)


{
  "statusCode": 401,
  "message": "Invalid API key"
}


{
  "statusCode": 401,
  "message": "Session expired"
}

Rate limit errors (429)


{
  "statusCode": 429,
  "message": "Rate limit exceeded",
  "error": "Too Many Requests"
}

Rate limit responses include a Retry-After header with the number of seconds to wait.

Server errors (500)


{
  "statusCode": 500,
  "message": "Internal server error"
}

Catching errors

The SDK uses ky under the hood. Failed requests throw an HTTPError with the response attached.


import { BurnerClient } from '@burnandclaim/sdk'
 
const client = new BurnerClient({ sessionToken: token })
 
try {
  const assets = await client.getWalletAssets(walletAddress)
} catch (err: unknown) {
  if (err && typeof err === 'object' && 'response' in err) {
    const response = (err as { response: Response }).response
    const body = await response.json()
    console.error(`API error ${body.statusCode}: ${body.message}`)
 
    if (response.status === 401) {
      // session expired or invalid -- recreate
    } else if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After')
      // wait and retry
    }
  } else {
    // network error, timeout, etc.
    throw err
  }
}

Error categories

Status	Meaning	Retry?
400	Bad request (validation failed)	No. Fix the request.
401	Unauthorized (bad key, expired session, wrong wallet)	No for bad key. Recreate for expired session.
403	Forbidden (scope insufficient)	No. Request a session with the required scope.
429	Rate limit exceeded	Yes, after `Retry-After` seconds.
500	Internal server error	Yes, with exponential backoff.
502/503	Service unavailable	Yes, with exponential backoff.

Submission errors

The submitTransactions endpoint returns per-transaction results. Individual transactions can fail even if the HTTP request succeeds:


const { results } = await client.submitTransactions(walletAddress, { signed })
 
for (const result of results) {
  if (result.status === 'failed') {
    console.error(`TX failed: ${result.error?.code} - ${result.error?.message}`)
    // Common codes:
    // - "TICKET_EXPIRED" -- the submission ticket has expired, rebuild
    // - "HASH_MISMATCH" -- the signed tx doesn't match the built tx
    // - "RPC_ERROR" -- Solana RPC rejected the transaction
  }
}

See Error Handling for retry strategies and best practices.