## Error Classes

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

```
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:

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