Errors

Every endpoint returns errors in one shape, and the SDK maps each status onto a typed class you can branch on.

The Error Envelope

Non-2xx responses always return this object:

{
  "error": "Validation failed",
  "code": "INVALID_PARAMS",
  "details": {
    "campaignId": ["Invalid campaign ID format. Expected <chainId>:<campaignIndex>"]
  }
}

error is a human-readable message, code is the stable machine-readable identifier to branch on, and details carries field-level messages on validation failures and is null otherwise.

API Error Codes

Status	`code`	What it means	What to do
400	`INVALID_PARAMS`	A path, query, or body parameter failed validation	Read `details`; it names the offending field. Check the API reference
404	`NOT_FOUND`	The campaign or claim proof does not exist	From `claims.get`, this is a normal state. See below
429	`RATE_LIMITED`	Per-IP rate limit exceeded	Back off. The SDK already retries with exponential backoff
500	`INTERNAL_ERROR`	Server-side failure	Retry with backoff; if it persists, tell us

A 404 from GET /v1/claims/{campaignId}/{address} has three causes, and two of them are ordinary: the address has no position in that campaign, or no published merkle root covers its rewards yet. Neither is a failure. Catch it and render an accruing state rather than an error.The third is different: the endpoint also 404s once the claim window has closed, even for a user who has a published, unclaimed leaf. Rendering “rewards accruing” there is wrong and permanent. Check campaign.endTime plus the claim window before choosing the copy.

import { TbiNotFoundError } from "@boostxyz/tbi-sdk";

let proof = null;
try {
  proof = await tbi.claims.get(id, userAddress);
} catch (e) {
  if (!(e instanceof TbiNotFoundError)) throw e;
  // No position, no root published yet, or the claim window has closed.
}

If you are checking many campaigns at once, claims.statuses avoids the problem entirely: campaigns without a published root report claimable: 0n instead of erroring. The same applies to referrals.proof: it 404s until the campaign has finalized and its referral root is published, which is the normal state for every live campaign.

Referral Bind Codes

POST /v1/referrals/bind (tbi.referrals.bind and submitBind) has its own rejection codes. The SDK raises them as TbiApiError, so branch on error.code.

Status	`code`	What it means	What to do
400	`SELF_REFERRAL`	The referrer is the referee, one of the referee’s proxy wallets, or a wallet of the referee’s own Rabbithole account	Continue without a referrer
401	`INVALID_SIGNATURE`	The signature is malformed, expired, not from the referee, or from a smart wallet (EIP-1271 is not supported)	Re-sign with a fresh deadline from an EOA
403	`WALLET_NOT_LINKED`	The referee’s wallet is not linked to a Rabbithole account	Ask the user to link the wallet, then bind again
409	`ALREADY_BOUND`	The referee is already bound to a different referrer. Binds are global and permanent	Continue; the existing bind stands
409	`REFERRER_NOT_LINKED`	The referrer’s wallet (after proxy canonicalization) is not linked to a Rabbithole account	Continue without a referrer; the link is not usable
409	`CYCLIC_REFERRAL`	The referrer is already referred by the referee, directly or through a chain of binds	Continue without a referrer

Re-submitting the exact same bind is not an error: it resolves with created: false. None of these codes should block a deposit. See Add Referrals for a worked handler.

The error-code set grows additively. Two more bind codes exist that the SDK never triggers: REFERRER_NOT_FOUND (404) when a raw REST bind sends a referrerUsername no account has claimed, and INVALID_SESSION (401) for Rabbithole’s own session-authenticated binds. Treat any code you do not recognise as a generic error.

SDK Error Classes

All SDK errors extend TbiError and carry a code.

Class	Raised when	Extends
`TbiError`	Base class, never thrown directly	`Error`
`TbiApiError`	Any non-2xx API response not covered below, including referral bind rejections	`TbiError`
`TbiNotFoundError`	HTTP 404: campaign, claim proof, or referral proof not found	`TbiApiError`
`TbiValidationError`	HTTP 400, the API rejected a parameter	`TbiApiError`
`TbiNetworkError`	`fetch` failed or the response body would not parse as JSON	`TbiError`
`TbiClaimError`	SDK-side claim validation: wrong wallet chain, proof/campaign mismatch, nothing claimable, or a batch spanning multiple reward chains	`TbiError`

Branch on the class, not the message:

import {
  TbiClaimError,
  TbiNetworkError,
  TbiNotFoundError,
  TbiValidationError,
} from "@boostxyz/tbi-sdk";

try {
  await tbi.claim({ walletClient, id, address });
} catch (e) {
  if (e instanceof TbiNotFoundError) return showAccruing();
  if (e instanceof TbiClaimError) return showNothingToClaim(e.message);
  if (e instanceof TbiValidationError) return reportBug(e);
  if (e instanceof TbiNetworkError) return showRetry();
  throw e;
}

Wallet write failures are not wrapped. A user rejecting the transaction, an out-of-gas error, or a contract revert propagates straight from your wallet client, so you can surface the wallet’s own message. See Contracts for the revert selectors.

What Retries Automatically

The SDK retries network errors, HTTP 429, and HTTP 5xx with exponential backoff of baseDelayMs * 2^(attempt - 1), defaulting to 3 total attempts and a 200 ms base. Other 4xx responses and aborted requests are never retried, because retrying them cannot succeed.

const tbi = createTbiClient({ retry: { attempts: 5, baseDelayMs: 500 } });

Pass an AbortSignal on any read method to cancel in-flight requests. A cancelled request is never retried:

const controller = new AbortController();
const campaign = await tbi.campaigns.get(id, { signal: controller.signal });

Contract Reverts

Once a claim transaction is submitted, failures come from the TBI Manager contract rather than the API.

Revert Selectors

InvalidProof, NothingToClaim, ClaimExpired, the referral claim errors, and the cause of each.

Get Started

Examples

Concepts

Guides

Reference

The Error Envelope

API Error Codes

Referral Bind Codes

SDK Error Classes

What Retries Automatically

Contract Reverts

Revert Selectors

Keep Exploring

Data Conventions

Claim Rewards

​The Error Envelope

​API Error Codes

​Referral Bind Codes

​SDK Error Classes

​What Retries Automatically

​Contract Reverts

Revert Selectors

​Keep Exploring

Data Conventions

Claim Rewards

The Error Envelope

API Error Codes

Referral Bind Codes

SDK Error Classes

What Retries Automatically

Contract Reverts

Keep Exploring