Error Handling
Essential guide to handling errors and exceptions in ModelRed SDK
⚠️
Essential Error Handling
Handle ModelRed SDK errors effectively with clear guidance on exception types and practical troubleshooting solutions.
Exception Types
ModelRed Exception Hierarchy
All exceptions inherit from ModelRedError, providing structured error handling.
PYTHON
from modelred import (
ModelRedError, # Base exception class
AuthenticationError, # API key issues
QuotaExceededError, # Usage limits exceeded
ModelNotFoundError, # Model doesn't exist
ValidationError, # Invalid parameters
AssessmentError, # Assessment problems
TierRestrictedError # Feature requires higher tier
)
# Basic error handling pattern
try:
async with ModelRed() as client:
result = await client.run_assessment(
model_id="my-model",
test_suites=["basic_security"]
)
except AuthenticationError as e:
print(f"🔑 Auth error: {e.message}")
except QuotaExceededError as e:
print(f"📊 Quota exceeded: {e.message}")
except ValidationError as e:
print(f"✅ Validation error: {e.message}")
except ModelRedError as e:
print(f"❌ General error: {e.message}")Authentication Errors
🔑 API Key & Permission Issues
Handle authentication failures and subscription tier restrictions.
AuthenticationError
Invalid or missing API key
Invalid API key or authentication failedTierRestrictedError
Feature requires higher tier
This feature requires Pro tier or higherPYTHON
from modelred import ModelRed, AuthenticationError, TierRestrictedError
async def handle_auth_errors():
try:
async with ModelRed(api_key="invalid-key") as client:
await client.validate_api_key()
except AuthenticationError:
print("🔑 Authentication failed:")
print(" 1. Check your API key is correct")
print(" 2. Ensure API key starts with 'mr_'")
print(" 3. Verify key hasn't expired")
except TierRestrictedError:
print("🔒 Feature restricted:")
print(" 1. Upgrade to required tier")
print(" 2. Use alternative features")
print(" 3. Contact support for options")Quota & Resource Errors
📊 Usage Limits & Resource Issues
Handle quota exceeded errors and missing resources.
PYTHON
from modelred import ModelRed, QuotaExceededError, ModelNotFoundError
async def handle_resource_errors():
async with ModelRed() as client:
try:
# Check usage before running assessment
usage = await client.get_usage_stats()
print(f"📊 Usage: {usage.assessments_this_month}/{usage.assessments_limit}")
if usage.assessments_this_month >= usage.assessments_limit:
print("⚠️ Warning: Assessment limit reached")
return
# Run assessment
result = await client.run_assessment(
model_id="test-model",
test_suites=["basic_security"]
)
except QuotaExceededError:
print("📊 Quota exceeded:")
print(" 1. Wait for quota reset")
print(" 2. Upgrade subscription tier")
print(" 3. Optimize assessment frequency")
except ModelNotFoundError:
print("🔍 Model not found:")
print(" 1. Check model ID spelling")
print(" 2. Verify model is registered")
print(" 3. List available models")
# Show available models
models = await client.list_models()
if models:
print("📋 Available models:")
for model in models[:3]:
print(f" • {model['modelId']}")Validation Errors
✅ Input Validation & Parameters
Handle invalid parameters and malformed requests.
PYTHON
from modelred import ModelRed, ValidationError, ModelProvider
async def handle_validation_errors():
async with ModelRed() as client:
try:
# Invalid model registration
await client.register_model(
model_id="", # Empty model ID - will fail
provider=ModelProvider.OPENAI,
provider_config={} # Empty config - will fail
)
except ValidationError as e:
print(f"✅ Validation error: {e.message}")
# Provide specific fixes based on error
if "model_id" in e.message.lower():
print("📋 Fix: Provide a non-empty model ID")
print(" Example: 'production-gpt-4'")
elif "provider_config" in e.message.lower():
print("📋 Fix: Add required provider configuration")
print(" Example: {'api_key': 'sk-...', 'model_name': 'gpt-4'}")
try:
# Invalid assessment parameters
await client.run_assessment(
model_id="valid-model",
test_suites=[], # Empty - will fail
priority="invalid" # Invalid priority
)
except ValidationError as e:
print(f"✅ Assessment error: {e.message}")
if "test_suites" in e.message.lower():
print("📋 Fix: Specify at least one test suite")
print(" Available: basic_security, content_safety, prompt_injection")
if "priority" in e.message.lower():
print("📋 Fix: Use valid priority")
print(" Valid: 'low', 'normal', 'high', 'critical'")Assessment Errors
🧪 Assessment Execution Issues
Handle assessment failures and execution problems.
PYTHON
from modelred import ModelRed, AssessmentError
async def handle_assessment_errors():
async with ModelRed() as client:
try:
result = await client.run_assessment(
model_id="problematic-model",
test_suites=["basic_security"],
wait_for_completion=True,
timeout_minutes=30
)
except AssessmentError as e:
print(f"🧪 Assessment failed: {e.message}")
error_msg = e.message.lower()
if "timeout" in error_msg:
print("📋 Timeout solutions:")
print(" 1. Increase timeout limit")
print(" 2. Run without waiting for completion")
print(" 3. Use fewer test suites")
elif "connection" in error_msg:
print("📋 Connection issues:")
print(" 1. Check model API credentials")
print(" 2. Verify provider endpoint")
print(" 3. Test network connectivity")
elif "data" in error_msg or "response" in error_msg:
print("📋 Model response issues:")
print(" 1. Verify model returns valid responses")
print(" 2. Check provider configuration")
print(" 3. Test model with simple prompt")
# Try basic recovery
print("🔄 Attempting basic recovery...")
try:
# Verify model exists
model_info = await client.get_model("problematic-model")
print(f"✅ Model found: {model_info.get('displayName', 'Unknown')}")
# Try minimal assessment
simple_result = await client.run_assessment(
model_id="problematic-model",
test_suites=["basic_security"],
wait_for_completion=False # Don't wait
)
print(f"✅ Basic assessment started: {simple_result.assessment_id}")
except Exception as recovery_error:
print(f"❌ Recovery failed: {recovery_error}")Best Practices
💡 Error Handling Best Practices
Exception Handling
✅Catch specific exceptions first
✅Log error details for debugging
✅Provide user-friendly messages
✅Include recovery suggestions
Prevention
✅Validate inputs before API calls
✅Check usage limits regularly
✅Test model configuration first
✅Use timeouts for long operations
Quick Reference
📚 Common Error Solutions
AuthenticationError
Check API key format (must start with 'mr_') and validity
QuotaExceededError
Wait for quota reset or upgrade subscription tier
ValidationError
Fix parameter validation issues and required fields
AssessmentError
Check model configuration and try simpler test suites
ModelNotFoundError
Verify model ID and registration status