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

# Terminal49 SDK Error Handling

> Catch and handle Terminal49 TypeScript SDK errors, including API validation failures and network timeouts, so your integration recovers gracefully.

The SDK throws typed errors you can catch and handle based on the error type.

## Error types

| Error                    | Cause                                      |
| ------------------------ | ------------------------------------------ |
| `AuthenticationError`    | Invalid or missing API key                 |
| `AuthorizationError`     | Valid API key but insufficient permissions |
| `NotFoundError`          | Resource doesn't exist or isn't accessible |
| `ValidationError`        | Invalid request parameters                 |
| `RateLimitError`         | Too many requests                          |
| `FeatureNotEnabledError` | Feature requires a plan upgrade            |
| `UpstreamError`          | Carrier or terminal API is unavailable     |
| `Terminal49Error`        | Generic error fallback                     |

## Basic error handling

```typescript theme={null}
import {
  Terminal49Client,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
} from '@terminal49/sdk';

const client = new Terminal49Client({
  apiToken: process.env.T49_API_TOKEN!,
});

try {
  await client.containers.get('container-uuid');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.error('Container not found');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited, retrying in 60s');
    await new Promise((resolve) => setTimeout(resolve, 60000));
  } else {
    throw error;
  }
}
```

## Automatic retries

The SDK automatically retries `429` and `5xx` responses with exponential backoff up to `maxRetries` (default: 2).

```typescript theme={null}
const client = new Terminal49Client({
  apiToken: process.env.T49_API_TOKEN!,
  maxRetries: 3,
});
```

## Error properties

All SDK errors include:

| Property  | Type    | Description                      |
| --------- | ------- | -------------------------------- |
| `message` | string  | Human-readable error description |
| `status`  | number  | HTTP status code                 |
| `details` | unknown | Raw error payload from the API   |