> ## 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.

# Rate limiting and retry configuration

> Configure Trustware SDK rate-limit handling: automatic retry with exponential backoff, max retry count, and callbacks for monitoring rate limit status.

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.

<Note>
  `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.
</Note>

## RetryConfig type

```ts theme={null}
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

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

## Properties

<ParamField path="retry.autoRetry" type="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`.
</ParamField>

<ParamField path="retry.maxRetries" type="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.
</ParamField>

<ParamField path="retry.baseDelayMs" type="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
</ParamField>

<ParamField path="retry.approachingThreshold" type="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.
</ParamField>

## Callbacks

<ParamField path="retry.onRateLimitInfo" type="(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.

  ```ts theme={null}
  onRateLimitInfo: (info) => {
    console.log(`${info.remaining} of ${info.limit} requests remaining`);
  }
  ```
</ParamField>

<ParamField path="retry.onRateLimited" type="(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.

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

<ParamField path="retry.onRateLimitApproaching" type="(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.

  ```ts theme={null}
  onRateLimitApproaching: (info, threshold) => {
    console.warn(`Approaching rate limit: ${info.remaining} requests left (threshold: ${threshold})`);
  }
  ```
</ParamField>

## RateLimitInfo shape

All three callbacks receive a `RateLimitInfo` object:

```ts theme={null}
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`.

<Warning>
  If `autoRetry` is `false`, the SDK will throw `RateLimitError` immediately on
  the first `429` without any retry attempts.
</Warning>

## Example

```ts theme={null}
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;
```