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

# Errors

> TypeScript SDK error classes — ComplianceError, APIError, ValidationError, UploadError and their subtypes

The SDK provides a hierarchy of error classes for different failure scenarios.

## Error Hierarchy

```
ComplianceError (base)
├── ValidationError
├── APIError
│   ├── NotFoundError
│   ├── UnauthorizedError
│   ├── ForbiddenError
│   ├── RateLimitError
│   ├── ServerError
│   ├── NetworkError
│   └── TimeoutError
└── UploadError
    ├── FileTooLargeError
    ├── UploadTimeoutError
    ├── InvalidFileTypeError
    ├── UploadAbortedError
    └── UploadUrlExpiredError
```

## ComplianceError

Base class for all SDK errors.

```typescript theme={null}
import { ComplianceError } from "@artu-ai/compliance-sdk";
```

### Properties

| Property  | Type                 | Description                  |
| --------- | -------------------- | ---------------------------- |
| `message` | `string`             | Human-readable error message |
| `code`    | `string`             | Error code                   |
| `cause`   | `Error \| undefined` | Original error if wrapped    |

### Methods

| Method     | Return Type | Description                 |
| ---------- | ----------- | --------------------------- |
| `toJSON()` | `object`    | Serializable representation |

## ValidationError

Thrown when input fails schema validation.

```typescript theme={null}
import { ValidationError } from "@artu-ai/compliance-sdk";
```

### Properties

| Property | Type                | Description                |
| -------- | ------------------- | -------------------------- |
| `issues` | `ValidationIssue[]` | Array of validation issues |

### ValidationIssue

```typescript theme={null}
interface ValidationIssue {
  path: (string | number)[];
  message: string;
  code: string;
}
```

### Example

```typescript theme={null}
try {
  await sdk.clients.create({ type: "invalid" });
} catch (error) {
  if (error instanceof ValidationError) {
    for (const issue of error.issues) {
      console.log(`${issue.path.join(".")}: ${issue.message}`);
    }
  }
}
```

## APIError

Base class for API-related errors.

```typescript theme={null}
import { APIError, isAPIError } from "@artu-ai/compliance-sdk";
```

### Properties

| Property     | Type                  | Description              |
| ------------ | --------------------- | ------------------------ |
| `statusCode` | `number`              | HTTP status code         |
| `requestId`  | `string \| undefined` | Request ID for debugging |

### Type Guard

```typescript theme={null}
if (isAPIError(error)) {
  console.log(error.statusCode);
}
```

## NotFoundError

Thrown when a resource is not found (404).

```typescript theme={null}
import { NotFoundError } from "@artu-ai/compliance-sdk";
```

### Properties

| Property       | Type                  | Description                  |
| -------------- | --------------------- | ---------------------------- |
| `resourceId`   | `string \| undefined` | ID of the missing resource   |
| `resourceType` | `string \| undefined` | Type of the missing resource |

### Example

```typescript theme={null}
try {
  await sdk.clients.retrieve("nonexistent_id");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log(`Resource not found: ${error.resourceId}`);
  }
}
```

## UnauthorizedError

Thrown when authentication fails (401).

```typescript theme={null}
import { UnauthorizedError } from "@artu-ai/compliance-sdk";
```

### Example

```typescript theme={null}
try {
  await sdk.clients.list();
} catch (error) {
  if (error instanceof UnauthorizedError) {
    console.log("Invalid API key");
  }
}
```

## ForbiddenError

Thrown when access is denied (403).

```typescript theme={null}
import { ForbiddenError } from "@artu-ai/compliance-sdk";
```

### Example

```typescript theme={null}
try {
  await sdk.alerts.generateReport("alert_id", "mex.actividad-vulnerable.avi");
} catch (error) {
  if (error instanceof ForbiddenError) {
    console.log("Insufficient permissions");
  }
}
```

## RateLimitError

Thrown when rate limit is exceeded (429).

```typescript theme={null}
import { RateLimitError } from "@artu-ai/compliance-sdk";
```

### Properties

| Property     | Type     | Description                  |
| ------------ | -------- | ---------------------------- |
| `retryAfter` | `number` | Seconds to wait before retry |

### Example

```typescript theme={null}
try {
  await sdk.clients.list();
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter} seconds`);
    await sleep(error.retryAfter * 1000);
  }
}
```

## ServerError

Thrown for server errors (5xx).

```typescript theme={null}
import { ServerError } from "@artu-ai/compliance-sdk";
```

### Example

```typescript theme={null}
try {
  await sdk.clients.list();
} catch (error) {
  if (error instanceof ServerError) {
    console.log(`Server error: ${error.requestId}`);
  }
}
```

## NetworkError

Thrown for network failures.

```typescript theme={null}
import { NetworkError } from "@artu-ai/compliance-sdk";
```

### Example

```typescript theme={null}
try {
  await sdk.clients.list();
} catch (error) {
  if (error instanceof NetworkError) {
    console.log("Network error - check connection");
  }
}
```

## TimeoutError

Thrown when request times out.

```typescript theme={null}
import { TimeoutError } from "@artu-ai/compliance-sdk";
```

### Example

```typescript theme={null}
try {
  await sdk.clients.list();
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log("Request timed out");
  }
}
```

## UploadError

Base class for upload-related errors.

```typescript theme={null}
import { UploadError, isUploadError } from "@artu-ai/compliance-sdk";
```

### Properties

| Property | Type          | Description               |
| -------- | ------------- | ------------------------- |
| `stage`  | `UploadStage` | Stage where upload failed |

### UploadStage

```typescript theme={null}
type UploadStage = "request" | "upload" | "confirm";
```

| Value       | Description                                |
| ----------- | ------------------------------------------ |
| `"request"` | Failed to request the presigned upload URL |
| `"upload"`  | Failed to upload the file bytes to storage |
| `"confirm"` | Failed to confirm the upload with the API  |

### Type Guard

```typescript theme={null}
if (isUploadError(error)) {
  console.log(`Upload failed at: ${error.stage}`);
}
```

## FileTooLargeError

Thrown when file exceeds size limit.

```typescript theme={null}
import { FileTooLargeError } from "@artu-ai/compliance-sdk";
```

### Properties

| Property     | Type     | Description                   |
| ------------ | -------- | ----------------------------- |
| `maxSize`    | `number` | Maximum allowed size in bytes |
| `actualSize` | `number` | Actual file size in bytes     |

## InvalidFileTypeError

Thrown for unsupported file types.

```typescript theme={null}
import { InvalidFileTypeError } from "@artu-ai/compliance-sdk";
```

### Properties

| Property       | Type       | Description        |
| -------------- | ---------- | ------------------ |
| `mimeType`     | `string`   | Actual MIME type   |
| `allowedTypes` | `string[]` | Allowed MIME types |

## UploadTimeoutError

Thrown when upload times out.

```typescript theme={null}
import { UploadTimeoutError } from "@artu-ai/compliance-sdk";
```

## UploadAbortedError

Thrown when upload is aborted.

```typescript theme={null}
import { UploadAbortedError } from "@artu-ai/compliance-sdk";
```

## UploadUrlExpiredError

Thrown when upload URL has expired.

```typescript theme={null}
import { UploadUrlExpiredError } from "@artu-ai/compliance-sdk";
```