Rate limiting and retry configuration

The Trustware SDK automatically retries requests that receive a 429 Too Many Requests response. The retry field in TrustwareConfigOptions lets you tune that behavior: how many times to retry, how long to wait between attempts, and whether to receive callbacks as the rate limit window fills up.

autoRetry controls client-side retry behavior only. It does not disable or modify backend rate limits; those are enforced server-side regardless of this setting.

RetryConfig type

type RetryConfig = {
  autoRetry?: boolean;
  maxRetries?: number;
  baseDelayMs?: number;
  approachingThreshold?: number;
  onRateLimitInfo?: (info: RateLimitInfo) => void;
  onRateLimited?: (info: RateLimitInfo, retryCount: number) => void;
  onRateLimitApproaching?: (info: RateLimitInfo, threshold: number) => void;
};

Default values

const DEFAULT_RETRY_CONFIG = {
  autoRetry: true,
  maxRetries: 3,
  baseDelayMs: 1000,
  approachingThreshold: 5,
};

Properties

boolean

default:"true"

When true, the SDK automatically retries any request that receives a 429 response, using exponential backoff calculated from baseDelayMs. Set to false to disable automatic retry and handle 429 responses yourself via onRateLimited.

number

default:"3"

The maximum number of retry attempts before the SDK gives up and throws a RateLimitError. Once this limit is exhausted, the error propagates to your onError callback if one is configured.

number

default:"1000"

The base delay in milliseconds used for exponential backoff. The delay before each retry attempt is calculated as baseDelayMs * 2^retryCount. With the default of 1000:

Retry 1: ~1 second
Retry 2: ~2 seconds
Retry 3: ~4 seconds

number

default:"5"

The number of remaining requests in the current rate limit window at which the SDK calls onRateLimitApproaching. For example, the default of 5 means the callback fires when 5 or fewer requests remain before the window resets.

Callbacks

(info: RateLimitInfo) => void

Called on every response that includes rate limit headers from the server, regardless of whether the limit has been reached. Use this for passive monitoring or to display a rate limit gauge in your UI.

onRateLimitInfo: (info) => {
  console.log(`${info.remaining} of ${info.limit} requests remaining`);
}

(info: RateLimitInfo, retryCount: number) => void

Called when a 429 response is received. retryCount is the current attempt number (starting at 1). Use this to log rate limit events or show a warning to the user.

onRateLimited: (info, retryCount) => {
  console.warn(`Rate limited. Retry attempt ${retryCount}. Resets at ${info.reset}`);
}

(info: RateLimitInfo, threshold: number) => void

Called when the remaining request count in the current window falls below approachingThreshold. Use this as an early warning to reduce request frequency before hitting the limit.

onRateLimitApproaching: (info, threshold) => {
  console.warn(`Approaching rate limit: ${info.remaining} requests left (threshold: ${threshold})`);
}

RateLimitInfo shape

All three callbacks receive a RateLimitInfo object:

type RateLimitInfo = {
  limit: number;      // Maximum requests allowed in the current window
  remaining: number;  // Requests remaining in the current window
  reset: number;      // Unix timestamp when the window resets
  retryAfter?: number; // Seconds until retry is allowed (only present on 429)
};

What happens when retries are exhausted

When maxRetries is reached without a successful response, the SDK throws a RateLimitError. If you have configured an onError callback on TrustwareConfigOptions, it will be called with that error. If you are using the headless API directly, the promise rejects with RateLimitError.

If autoRetry is false, the SDK will throw RateLimitError immediately on the first 429 without any retry attempts.

Example

const config = {
  apiKey: process.env.NEXT_PUBLIC_TRUSTWARE_API_KEY!,
  routes: {
    toChain: "8453",
    toToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  },
  retry: {
    autoRetry: true,
    maxRetries: 3,
    baseDelayMs: 1000,
    approachingThreshold: 5,
    onRateLimitApproaching: (info, threshold) => {
      console.warn(`Rate limit approaching: ${info.remaining} requests remaining`);
    },
    onRateLimited: (info, retryCount) => {
      console.warn(`Rate limited on attempt ${retryCount}. Resets at ${new Date(info.reset * 1000).toISOString()}`);
    },
  },
} satisfies TrustwareConfigOptions;

Get Started

Integration

Configuration

Events & Errors

Guides

SDK Reference

Rate limiting and retry configuration

RetryConfig type

Default values

Properties

Callbacks

RateLimitInfo shape

What happens when retries are exhausted

Example

​RetryConfig type

​Default values

​Properties

​Callbacks

​RateLimitInfo shape

​What happens when retries are exhausted

​Example

RetryConfig type

Default values

Properties

Callbacks

RateLimitInfo shape

What happens when retries are exhausted

Example