Rate limiting and retry configuration

The Trustware API is rate limited per API key, and that limit is shared by everyone using your key rather than applied per end user. A busy site can reach it during normal traffic, so treat a 429 as an operating condition rather than an edge case. Your key’s limit, its remaining requests, and the window boundary come back on every response as X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, plus Retry-After on a 429. The SDK retries on the schedule those headers state and keeps no schedule of its own.

Server-directed retry requires @trustware/sdk 1.1.11 or later.Through 1.1.10, retry also accepted autoRetry, maxRetries, and baseDelayMs, and the SDK retried up to maxRetries times using baseDelayMs * 2^retryCount whenever a 429 carried no Retry-After. Those three fields are no longer accepted in 1.1.11. Remove them when you upgrade.

How the SDK retries

On a 429, the SDK reads the wait from Retry-After. If that header is missing it falls back to X-RateLimit-Reset, which points at the end of the same window.
It waits exactly that long and retries, repeating for as long as the server keeps stating a wait.
If the total time waited would pass 10 seconds, the SDK stops and throws RateLimitError with retriesExhausted: false. The wait is in rateLimitInfo.retryAfter, so your UI can tell the user when to come back instead of holding a spinner.
If a response carries no usable timing at all, the SDK stops immediately and throws RateLimitError with retriesExhausted: true.

There is no retry counter and no backoff curve. The limit is a fixed window, so an invented delay either lands inside the same window and fails again, or overshoots one the SDK could have read exactly. The 10 second budget is the only number the SDK picks, because how long your app can afford to block is a property of your app.

Retry timing is not configurable. No client setting can widen a server-side limit. If you need more headroom, ask Trustware to raise the limit on your key.

RetryConfig type

retry configures observability only:

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

Properties

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 every time a 429 response is received, before the SDK waits. retryCount is the number of retries already made for this request, so it is 0 on the first 429. Use this to log rate limit events or show a warning to the user.

onRateLimited: (info, retryCount) => {
  console.warn(`Rate limited. Retries so far: ${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)
};

When the SDK gives up

The SDK throws RateLimitError, which extends the native Error class rather than TrustwareError. Your onError callback is not called, because that callback takes a TrustwareError, and an instanceof TrustwareError check will not match it. Catch RateLimitError around your own calls. retriesExhausted tells you which of the two cases you are in:

`retriesExhausted`	Meaning	What to do
`false`	The wait is known and is simply longer than the SDK will block for. `rateLimitInfo.retryAfter` holds it.	Show the user when to come back, then retry after that point.
`true`	The response carried no usable `Retry-After` or `X-RateLimit-Reset`, so there was no schedule to retry against.	Back off and retry later. In a browser, check that your requests are not passing through a proxy that strips the rate limit headers.

Mind the units when you render the wait: retryAfter is a number of seconds from now, while reset is a Unix timestamp.

import { RateLimitError, Trustware } from "@trustware/sdk";

try {
  await Trustware.runTopUp({ fromAmount: "1000000" });
} catch (error) {
  if (error instanceof RateLimitError) {
    const { retryAfter, reset } = error.rateLimitInfo;

    if (error.retriesExhausted || !retryAfter) {
      showGenericBusy(new Date(reset * 1000));
    } else {
      showRetryAt(new Date(Date.now() + retryAfter * 1000));
    }
    return;
  }
  throw error;
}

Example

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

Get Started

Integration

Configuration

Events & Errors

Guides

SDK Reference

Rate limiting and retry configuration

How the SDK retries

RetryConfig type

Properties

Callbacks

RateLimitInfo shape

When the SDK gives up

Example

​How the SDK retries

​RetryConfig type

​Properties

​Callbacks

​RateLimitInfo shape

​When the SDK gives up

​Example

How the SDK retries

RetryConfig type

Properties

Callbacks

RateLimitInfo shape

When the SDK gives up

Example