> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retry

> Configure automatic retry behavior for failed requests

## Overview

The GBOX SDK automatically retries certain types of failed requests to improve reliability. By default, retry is disabled (0 retries), but you can configure this behavior based on your needs.

## Automatic Retry Conditions

The SDK will automatically retry requests that fail due to:

* **Connection errors** (network connectivity issues)
* **408 Request Timeout**
* **409 Conflict**
* **429 Rate Limit**
* **5xx Server Errors** (500, 502, 503, etc.)

## Configuration

### Global Retry Settings

Configure retry behavior when initializing the SDK:

<CodeGroup>
  ```typescript Basic Retry Configuration theme={null}
  import GboxSDK from "gbox-sdk";

  const gboxSDK = new GboxSDK({
    apiKey: process.env["GBOX_API_KEY"],
    maxRetries: 3, // Retry up to 3 times (default is 0)
  });
  ```

  ```typescript Advanced Configuration theme={null}
  import GboxSDK from "gbox-sdk";

  const gboxSDK = new GboxSDK({
    apiKey: process.env["GBOX_API_KEY"],
    maxRetries: 5,
    timeout: 30 * 1000, // 30 seconds timeout per request
  });
  ```
</CodeGroup>

### Per-Request Retry Settings

Override retry settings for specific requests:

<CodeGroup>
  ```typescript Override for Device Creation theme={null}
  // Create device with custom retry settings
  const box = await gboxSDK.create(
    { type: "android" },
    {
      maxRetries: 5, // Retry up to 5 times for this request
    }
  );
  ```

  ```typescript Override for Critical Operations theme={null}
  // Use higher retry count for important operations
  await gboxSDK.startBox(
    { id: boxId },
    {
      maxRetries: 10,
      timeout: 60 * 1000, // 60 seconds timeout
    }
  );
  ```
</CodeGroup>

## Retry Behavior

### Exponential Backoff

The SDK uses exponential backoff between retries:

* **1st retry**: \~1 second delay
* **2nd retry**: \~2 seconds delay
* **3rd retry**: \~4 seconds delay
* And so on...

### Example Usage

```typescript theme={null}
import GboxSDK from "gbox-sdk";

const gboxSDK = new GboxSDK({
  apiKey: process.env["GBOX_API_KEY"],
  maxRetries: 3,
});

async function createDeviceWithRetry() {
  try {
    const box = await gboxSDK.create({ type: "android" });
    console.log("Device created successfully:", box.id);
    return box;
  } catch (error) {
    console.error("Failed to create device after retries:", error);
    throw error;
  }
}

createDeviceWithRetry();
```

## Best Practices

* **Start with low retry counts** (2-3) and increase if needed
* **Use higher retry counts** for critical operations
* **Set appropriate timeouts** to avoid long waits
* **Handle final failures** gracefully in your application
* **Monitor retry patterns** to identify infrastructure issues

## Disable Retries

To disable automatic retries completely:

```typescript theme={null}
const gboxSDK = new GboxSDK({
  apiKey: process.env["GBOX_API_KEY"],
  maxRetries: 0, // Disable retries
});
```