Skip to main content

SDK Exception Hierarchy

Every exception raised by the SDK inherits from ValiqorError, so you can catch all SDK errors in one place.
from valiqor import ValiqorError

try:
    result = client.eval.evaluate(dataset=data, metrics=["coherence"])
except ValiqorError as e:
    print(f"Valiqor error: {e}")

Full hierarchy

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

Common Errors and Resolutions

AuthenticationError

HTTP status: 401 or 403
MessageCauseResolution
API key required. Pass api_key parameter or set VALIQOR_API_KEY env var.No API key providedSet VALIQOR_API_KEY environment variable or pass api_key to the client constructor
Invalid API key format. Keys should start with 'vq_'Key doesn’t have the vq_ prefixRegenerate your key at the dashboard or with valiqor keys create
Invalid or expired API keyKey has been revoked or expiredRun valiqor login to re-authenticate
Access forbidden. Check your API key permissions.Key doesn’t have the required permissionsVerify you’re using the correct key for this project
from valiqor import AuthenticationError

try:
    result = client.eval.evaluate(dataset=data, metrics=["coherence"])
except AuthenticationError as e:
    print(f"Auth failed: {e}")

AccountDeactivatedError

HTTP status: 403 Your account has been deactivated by an administrator. Contact support or visit app.valiqor.com/account.

RateLimitError

HTTP status: 429 Too many requests in a short window. The SDK provides a retry_after attribute.
from valiqor import RateLimitError
import time

try:
    result = client.eval.evaluate(dataset=data, metrics=["coherence"])
except RateLimitError as e:
    print(f"Rate limited. Retry in {e.retry_after}s")
    time.sleep(e.retry_after or 5)
See Rate Limits for exact limits.

QuotaExceededError

HTTP status: 429 (quota exceeded) or 403 (trial expired) Your monthly API call quota has been used up.
from valiqor import QuotaExceededError

try:
    result = client.failure_analysis.run(dataset=data)
except QuotaExceededError as e:
    print(f"Usage: {e.current_usage}/{e.quota_limit} ({e.service})")
Resolutions:
  • Check usage with client.get_usage() or valiqor status
  • Upgrade your plan for a higher quota
  • If you see "Verify your email to unlock 50 free runs", run valiqor verify

TokenQuotaExceededError

HTTP status: 429 Monthly LLM token quota exceeded. Same as QuotaExceededError but with token-specific attributes.
from valiqor import TokenQuotaExceededError

try:
    result = client.eval.evaluate(dataset=data, metrics=["coherence"])
except TokenQuotaExceededError as e:
    print(f"Tokens: {e.current_tokens}/{e.token_limit}")
    print(f"This request would use ~{e.predicted_tokens} tokens")

ValidationError

HTTP status: 400 Invalid request parameters or dataset format.
Common CauseResolution
Missing required fields in dataset itemsEnsure each item has at minimum input and output keys
Invalid metric nameUse client.eval.list_metric_templates() to see available metrics
Project not foundCheck project name with valiqor config show

DatasetTooLargeError

HTTP status: 400 Dataset exceeds the maximum size limit (1,000 items per request).
from valiqor import DatasetTooLargeError

try:
    result = client.eval.evaluate(dataset=large_data, metrics=["coherence"])
except DatasetTooLargeError as e:
    print(f"Dataset: {e.dataset_size} items (max: {e.max_allowed})")
Resolution: Split your dataset into batches.

TimeoutError

Request took longer than the 300-second (5-minute) default timeout. Resolutions:
  • Use async mode for large datasets: client.eval.evaluate_async(...) or client.failure_analysis.run_async(...)
  • Reduce dataset size

NetworkError

Cannot reach the Valiqor backend.
MessageCauseResolution
Failed to connect to ...Backend unreachableCheck internet connection; verify backend URL in .valiqorrc
Request failed: ...Generic network failureRetry the request

UploadError

File upload failed (subclass of NetworkError).
CauseResolution
Invalid API key during uploadRun valiqor login to refresh credentials
File not found or invalid JSONVerify the file path and format

ServiceUnavailableError

HTTP status: 503 The backend is temporarily overloaded. The SDK automatically retries once after a short delay. If the retry also fails, this error is raised.
from valiqor import ServiceUnavailableError

try:
    result = client.eval.evaluate(dataset=data, metrics=["coherence"])
except ServiceUnavailableError as e:
    print(f"Service unavailable: {e}")
    print(f"Suggested retry after: {e.retry_after}s")

APIError

HTTP status: 500+ (generic server error) An unexpected backend error. Includes status_code and response attributes for debugging.
from valiqor import APIError

try:
    result = client.eval.evaluate(dataset=data, metrics=["coherence"])
except APIError as e:
    print(f"Server error {e.status_code}: {e}")
    print(f"Response: {e.response}")

Module-Specific Errors

TracingError

Raised when tracing operations fail (e.g. malformed trace data, span nesting issues).

ScanError

Raised when scanner operations fail (e.g. repository path doesn’t exist).

EvaluationError

Raised for evaluation-specific failures.

SecurityError

Raised for security audit or red team failures.

Module Not Installed

Each SDK module is lazily loaded. If a module fails to load, you’ll see an ImportError:
AccessErrorFix
client.evalEval module not availablepip install valiqor
client.securitySecurity module not availablepip install valiqor
client.traceTrace module not availablepip install valiqor
client.scannerScanner module not availablepip install valiqor
client.failure_analysisFailure analysis module not availablepip install valiqor
client.tracesTrace query module not availablepip install valiqor
All modules are included in the base package:
pip install valiqor

CLI Issues

Login fails

SymptomResolution
httpx not installedRun pip install httpx — required for the login flow
Authorization timed outRe-run valiqor login; the device code expires after a few minutes
Authorization deniedApprove the request in your browser when prompted
Direct login not availableThe backend doesn’t support email/password login; use valiqor login for browser-based auth

Configuration problems

SymptomResolution
Valiqor not configuredRun valiqor config to create a .valiqorrc file
Configuration has errorsRun valiqor config to fix missing or invalid settings
Unknown config keyCheck allowed keys: project_name, api_key, trace_dir, scan_dir, environment, valiqor_intelligence, debug, openai_api_key

Upload fails

SymptomResolution
No Valiqor API key configuredRun valiqor login or set VALIQOR_API_KEY
No files found to uploadCheck that trace/scan files exist in the configured directories
Path not foundVerify the path you passed to valiqor upload

Auto-Retry Behaviour

The SDK automatically retries in one scenario:
Status CodeBehaviour
503Waits briefly, then retries once. If the retry also returns 503, raises ServiceUnavailableError.
All other error status codes raise immediately with no automatic retry.