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

# Error Handling

> Typed errors and retry behavior in the Node.js SDK

## Error Classes

The SDK throws typed errors so you can handle specific failure cases. All errors include a `requestId` for debugging.

```typescript theme={null}
import UpliftAI, {
  UpliftAIError,
  UpliftAIAuthError,                // 401
  UpliftAIInsufficientBalanceError,  // 402
  UpliftAIRateLimitError,            // 429
} from '@upliftai/sdk-js';

const client = new UpliftAI({
  apiKey: 'your-api-key',
});

try {
  const { audio } = await client.tts.create({
    text: 'ٹیسٹ',
    voiceId: 'v_meklc281',
  });
} catch (err) {
  if (err instanceof UpliftAIAuthError) {
    // 401 — invalid or missing API key
    console.error('Check your API key');
  } else if (err instanceof UpliftAIRateLimitError) {
    // 429 — rate limited (auto-retried based on maxRetries)
    console.error('Rate limited, back off and retry');
  } else if (err instanceof UpliftAIInsufficientBalanceError) {
    // 402 — top up your account
    console.error('Insufficient balance');
  } else if (err instanceof UpliftAIError) {
    // Other API errors
    console.error(err.statusCode, err.code, err.requestId);
  }
}
```

## Automatic Retries

The SDK automatically retries on transient errors with exponential backoff and jitter:

| Status Code | Description           | Auto-Retried? |
| ----------- | --------------------- | ------------- |
| `408`       | Request Timeout       | Yes           |
| `429`       | Rate Limited          | Yes           |
| `500`       | Internal Server Error | Yes           |
| `502`       | Bad Gateway           | Yes           |
| `503`       | Service Unavailable   | Yes           |
| `504`       | Gateway Timeout       | Yes           |
| `401`       | Unauthorized          | No            |
| `402`       | Insufficient Balance  | No            |
| `400`       | Bad Request           | No            |

Configure retry behavior via the `maxRetries` client option:

```typescript theme={null}
const client = new UpliftAI({
  apiKey: 'your-api-key',
  maxRetries: 3, // default is 2
  timeout: 60000, // default is 30000ms
});
```