Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trustware.io/llms.txt

Use this file to discover all available pages before exploring further.

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

​
retry.autoRetry
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.
​
retry.maxRetries
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.
​
retry.baseDelayMs
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
​
retry.approachingThreshold
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

​
retry.onRateLimitInfo
(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`);
}
​
retry.onRateLimited
(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}`);
}
​
retry.onRateLimitApproaching
(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;