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

# Exceptions

> Complete reference for all Valiqor exception types with causes and resolution steps.

## Overview

All Valiqor exceptions inherit from `ValiqorError`. Catch this base class to handle any SDK error, or catch specific subclasses for granular error handling.

```python theme={"system"}
from valiqor.common.exceptions import ValiqorError, AuthenticationError, RateLimitError

try:
    result = client.eval.evaluate(dataset=data, metrics=["hallucination"])
except AuthenticationError:
    print("Invalid API key — check VALIQOR_API_KEY")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except ValiqorError as e:
    print(f"Valiqor error: {e}")
```

***

## Exception Hierarchy

```
ValiqorError
├── ConfigurationError
├── AuthenticationError
│   └── AccountDeactivatedError
├── RateLimitError
├── QuotaExceededError
│   └── TokenQuotaExceededError
├── ValidationError
│   └── DatasetTooLargeError
├── TimeoutError
├── NetworkError
│   └── UploadError
├── APIError
│   └── ServiceUnavailableError
├── TracingError
├── ScanError
├── EvaluationError
└── SecurityError
```

***

## Base Exception

### `ValiqorError`

Base class for all Valiqor SDK errors.

```python theme={"system"}
class ValiqorError(Exception):
    def __init__(self, message: str)
```

***

## Authentication Errors

### `ConfigurationError`

Raised when the SDK is misconfigured — missing API key, invalid config file, or incompatible settings.

```python theme={"system"}
class ConfigurationError(ValiqorError)
```

| Common Cause         | Resolution                                                |
| -------------------- | --------------------------------------------------------- |
| Missing API key      | Set `VALIQOR_API_KEY` env var or pass `api_key` to client |
| Invalid `.valiqorrc` | Check JSON syntax in your config file                     |
| Missing project name | Set `VALIQOR_PROJECT_NAME` or pass `project_name`         |

***

### `AuthenticationError`

Raised when the API key is invalid, expired, or unauthorized.

```python theme={"system"}
class AuthenticationError(ValiqorError)
```

| Common Cause    | Resolution                                       |
| --------------- | ------------------------------------------------ |
| Invalid API key | Regenerate at dashboard or `valiqor keys create` |
| Expired key     | Create a new key                                 |
| Wrong org       | Check you're using the correct key for your org  |

***

### `AccountDeactivatedError`

Raised when the account has been deactivated.

```python theme={"system"}
class AccountDeactivatedError(AuthenticationError)
```

***

## Rate & Quota Errors

### `RateLimitError`

Raised when too many requests are sent in a short period.

```python theme={"system"}
class RateLimitError(ValiqorError):
    def __init__(self, message: str, retry_after: int = None)
```

| Attribute     | Type            | Description                      |
| ------------- | --------------- | -------------------------------- |
| `retry_after` | `Optional[int]` | Seconds to wait before retrying. |

| Resolution                                                                 |
| -------------------------------------------------------------------------- |
| Wait for `retry_after` seconds, then retry. Consider adding backoff logic. |

***

### `QuotaExceededError`

Raised when monthly usage quota is reached.

```python theme={"system"}
class QuotaExceededError(ValiqorError):
    def __init__(self, message: str, current_usage: int = None, quota_limit: int = None, service: str = None)
```

| Attribute       | Type            | Description                                        |
| --------------- | --------------- | -------------------------------------------------- |
| `current_usage` | `Optional[int]` | Current usage count.                               |
| `quota_limit`   | `Optional[int]` | Maximum allowed.                                   |
| `service`       | `Optional[str]` | Which service hit the limit (e.g. `"evaluation"`). |

***

### `TokenQuotaExceededError`

Raised when token usage quota is exceeded (subclass of `QuotaExceededError`).

```python theme={"system"}
class TokenQuotaExceededError(QuotaExceededError):
    def __init__(self, message: str, current_tokens: int = None, predicted_tokens: int = None, token_limit: int = None, service: str = None)
```

| Attribute          | Type            | Description                       |
| ------------------ | --------------- | --------------------------------- |
| `current_tokens`   | `Optional[int]` | Tokens used so far.               |
| `predicted_tokens` | `Optional[int]` | Predicted tokens for the request. |
| `token_limit`      | `Optional[int]` | Token quota limit.                |

***

## Validation Errors

### `ValidationError`

Raised when input data fails validation — bad format, missing fields, or invalid parameters.

```python theme={"system"}
class ValidationError(ValiqorError)
```

| Common Cause            | Resolution                                     |
| ----------------------- | ---------------------------------------------- |
| Missing required fields | Ensure dataset items have `input` and `output` |
| Invalid metric name     | Check `list_metric_templates()` for valid keys |
| Invalid parameter value | Check parameter docs for accepted values       |

***

### `DatasetTooLargeError`

Raised when the dataset exceeds the maximum allowed size.

```python theme={"system"}
class DatasetTooLargeError(ValidationError):
    def __init__(self, message: str, dataset_size: int = None, max_allowed: int = None)
```

| Attribute      | Type            | Description                     |
| -------------- | --------------- | ------------------------------- |
| `dataset_size` | `Optional[int]` | Number of items in the dataset. |
| `max_allowed`  | `Optional[int]` | Maximum allowed items.          |

| Resolution                                             |
| ------------------------------------------------------ |
| Split dataset into smaller batches, or use async mode. |

***

## Network & Timeout Errors

### `TimeoutError`

Raised when a request exceeds the timeout duration.

```python theme={"system"}
class TimeoutError(ValiqorError)
```

| Resolution                                                          |
| ------------------------------------------------------------------- |
| Increase `timeout` parameter, or use async mode for large datasets. |

***

### `NetworkError`

Raised when the SDK cannot reach the backend.

```python theme={"system"}
class NetworkError(ValiqorError)
```

| Common Cause           | Resolution                    |
| ---------------------- | ----------------------------- |
| No internet connection | Check connectivity            |
| Backend URL incorrect  | Verify `VALIQOR_BACKEND_URL`  |
| DNS resolution failure | Check firewall/proxy settings |

***

### `UploadError`

Raised when a trace or scan upload fails (subclass of `NetworkError`).

```python theme={"system"}
class UploadError(NetworkError)
```

***

## API Errors

### `APIError`

Generic API error with status code and response details.

```python theme={"system"}
class APIError(ValiqorError):
    def __init__(self, message: str, status_code: int = None, response: dict = None)
```

| Attribute     | Type             | Description         |
| ------------- | ---------------- | ------------------- |
| `status_code` | `Optional[int]`  | HTTP status code.   |
| `response`    | `Optional[dict]` | Full response body. |

***

### `ServiceUnavailableError`

Raised when the backend is temporarily unavailable (503).

```python theme={"system"}
class ServiceUnavailableError(APIError):
    def __init__(self, message: str, retry_after: int = None, response: dict = None)
```

| Attribute     | Type            | Description                      |
| ------------- | --------------- | -------------------------------- |
| `retry_after` | `Optional[int]` | Seconds to wait before retrying. |

***

## Module-Specific Errors

### `TracingError`

Raised for errors during trace capture or export.

```python theme={"system"}
class TracingError(ValiqorError)
```

### `ScanError`

Raised for errors during code scanning.

```python theme={"system"}
class ScanError(ValiqorError)
```

### `EvaluationError`

Raised for errors during evaluation runs.

```python theme={"system"}
class EvaluationError(ValiqorError)
```

### `SecurityError`

Raised for errors during security audits or red team runs.

```python theme={"system"}
class SecurityError(ValiqorError)
```

***

## Error Handling Pattern

```python theme={"system"}
from valiqor import ValiqorClient
from valiqor.common.exceptions import (
    ValiqorError,
    AuthenticationError,
    RateLimitError,
    QuotaExceededError,
    DatasetTooLargeError,
    TimeoutError,
)
import time

client = ValiqorClient()

def run_with_retry(dataset, metrics, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.eval.evaluate(dataset=dataset, metrics=metrics)
        except RateLimitError as e:
            wait = e.retry_after or (2 ** attempt)
            print(f"Rate limited, waiting {wait}s...")
            time.sleep(wait)
        except DatasetTooLargeError as e:
            print(f"Dataset too large ({e.dataset_size} items, max {e.max_allowed})")
            raise
        except QuotaExceededError as e:
            print(f"Quota exceeded: {e.current_usage}/{e.quota_limit}")
            raise
        except TimeoutError:
            print("Timeout — switching to async mode")
            return client.eval.evaluate_async(dataset=dataset, metrics=metrics)
        except AuthenticationError:
            print("Auth failed — check your API key")
            raise
    raise ValiqorError("Max retries exceeded")
```

***

## Related

* [Troubleshooting](/resources/troubleshooting) — Common issues and fixes
* [Configuration](/sdk/configuration) — Avoid `ConfigurationError`
* [Rate Limits](/resources/rate-limits) — Understand rate and quota limits