SDK Exception Hierarchy
Every exception raised by the SDK inherits fromValiqorError, so you can catch all SDK errors in one place.
Full hierarchy
Common Errors and Resolutions
AuthenticationError
HTTP status: 401 or 403| Message | Cause | Resolution |
|---|---|---|
API key required. Pass api_key parameter or set VALIQOR_API_KEY env var. | No API key provided | Set 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_ prefix | Regenerate your key at the dashboard or with valiqor keys create |
Invalid or expired API key | Key has been revoked or expired | Run valiqor login to re-authenticate |
Access forbidden. Check your API key permissions. | Key doesn’t have the required permissions | Verify you’re using the correct key for this project |
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 aretry_after attribute.
QuotaExceededError
HTTP status: 429 (quota exceeded) or 403 (trial expired) Your monthly API call quota has been used up.- Check usage with
client.get_usage()orvaliqor status - Upgrade your plan for a higher quota
- If you see
"Verify your email to unlock 50 free runs", runvaliqor verify
TokenQuotaExceededError
HTTP status: 429 Monthly LLM token quota exceeded. Same asQuotaExceededError but with token-specific attributes.
ValidationError
HTTP status: 400 Invalid request parameters or dataset format.| Common Cause | Resolution |
|---|---|
| Missing required fields in dataset items | Ensure each item has at minimum input and output keys |
| Invalid metric name | Use client.eval.list_metric_templates() to see available metrics |
| Project not found | Check project name with valiqor config show |
DatasetTooLargeError
HTTP status: 400 Dataset exceeds the maximum size limit (1,000 items per request).TimeoutError
Request took longer than the 300-second (5-minute) default timeout. Resolutions:- Use async mode for large datasets:
client.eval.evaluate_async(...)orclient.failure_analysis.run_async(...) - Reduce dataset size
NetworkError
Cannot reach the Valiqor backend.| Message | Cause | Resolution |
|---|---|---|
Failed to connect to ... | Backend unreachable | Check internet connection; verify backend URL in .valiqorrc |
Request failed: ... | Generic network failure | Retry the request |
UploadError
File upload failed (subclass ofNetworkError).
| Cause | Resolution |
|---|---|
| Invalid API key during upload | Run valiqor login to refresh credentials |
| File not found or invalid JSON | Verify 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.APIError
HTTP status: 500+ (generic server error) An unexpected backend error. Includesstatus_code and response attributes for debugging.
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 anImportError:
| Access | Error | Fix |
|---|---|---|
client.eval | Eval module not available | pip install valiqor |
client.security | Security module not available | pip install valiqor |
client.trace | Trace module not available | pip install valiqor |
client.scanner | Scanner module not available | pip install valiqor |
client.failure_analysis | Failure analysis module not available | pip install valiqor |
client.traces | Trace query module not available | pip install valiqor |
CLI Issues
Login fails
| Symptom | Resolution |
|---|---|
httpx not installed | Run pip install httpx — required for the login flow |
Authorization timed out | Re-run valiqor login; the device code expires after a few minutes |
Authorization denied | Approve the request in your browser when prompted |
Direct login not available | The backend doesn’t support email/password login; use valiqor login for browser-based auth |
Configuration problems
| Symptom | Resolution |
|---|---|
Valiqor not configured | Run valiqor config to create a .valiqorrc file |
Configuration has errors | Run valiqor config to fix missing or invalid settings |
Unknown config key | Check allowed keys: project_name, api_key, trace_dir, scan_dir, environment, valiqor_intelligence, debug, openai_api_key |
Upload fails
| Symptom | Resolution |
|---|---|
No Valiqor API key configured | Run valiqor login or set VALIQOR_API_KEY |
No files found to upload | Check that trace/scan files exist in the configured directories |
Path not found | Verify the path you passed to valiqor upload |
Auto-Retry Behaviour
The SDK automatically retries in one scenario:| Status Code | Behaviour |
|---|---|
| 503 | Waits briefly, then retries once. If the retry also returns 503, raises ServiceUnavailableError. |