Skip to main content

​
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 CauseResolution
Missing API keySet VALIQOR_API_KEY env var or pass api_key to client
Invalid .valiqorrcCheck JSON syntax in your config file
Missing project nameSet VALIQOR_PROJECT_NAME or pass project_name

​
AuthenticationError

Raised when the API key is invalid, expired, or unauthorized. 
class AuthenticationError(ValiqorError)
Common CauseResolution
Invalid API keyRegenerate at dashboard or valiqor keys create
Expired keyCreate a new key
Wrong orgCheck 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)
AttributeTypeDescription
retry_afterOptional[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)
AttributeTypeDescription
current_usageOptional[int]Current usage count.
quota_limitOptional[int]Maximum allowed.
serviceOptional[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)
AttributeTypeDescription
current_tokensOptional[int]Tokens used so far.
predicted_tokensOptional[int]Predicted tokens for the request.
token_limitOptional[int]Token quota limit.

​
Validation Errors

​
ValidationError

Raised when input data fails validation — bad format, missing fields, or invalid parameters. 
class ValidationError(ValiqorError)
Common CauseResolution
Missing required fieldsEnsure dataset items have input and output
Invalid metric nameCheck list_metric_templates() for valid keys
Invalid parameter valueCheck parameter docs for accepted values

​
DatasetTooLargeError

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)
AttributeTypeDescription
dataset_sizeOptional[int]Number of items in the dataset.
max_allowedOptional[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 CauseResolution
No internet connectionCheck connectivity
Backend URL incorrectVerify VALIQOR_BACKEND_URL
DNS resolution failureCheck 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)
AttributeTypeDescription
status_codeOptional[int]HTTP status code.
responseOptional[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)
AttributeTypeDescription
retry_afterOptional[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")