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.
Overview
All Valiqor exceptions inherit from ValiqorError. Catch this base class to handle any SDK error, or catch specific subclasses for granular error handling.
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.
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.
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.
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.
class AccountDeactivatedError(AuthenticationError)
Rate & Quota Errors
RateLimitError
Raised when too many requests are sent in a short period.
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.
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).
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.
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 |
Raised when the dataset exceeds the maximum allowed size.
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.
class TimeoutError(ValiqorError)
| Resolution |
|---|
Increase timeout parameter, or use async mode for large datasets. |
NetworkError
Raised when the SDK cannot reach the backend.
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).
class UploadError(NetworkError)
API Errors
APIError
Generic API error with status code and response details.
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).
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.
class TracingError(ValiqorError)
ScanError
Raised for errors during code scanning.
class ScanError(ValiqorError)
EvaluationError
Raised for errors during evaluation runs.
class EvaluationError(ValiqorError)
SecurityError
Raised for errors during security audits or red team runs.
class SecurityError(ValiqorError)
Error Handling Pattern
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")
