Error Handling
Understanding error handling and execution statuses in Bifrost
Execution Statuses
Section titled “Execution Statuses”Every workflow and script execution goes through various states and can complete with different statuses:
Status Types
Section titled “Status Types”- SUCCESS: Execution completed successfully with no errors
- FAILED: Execution encountered an exception and could not complete
- COMPLETED_WITH_ERRORS: Execution completed but returned explicit failure result
- TIMEOUT: Execution exceeded the configured timeout limit
- CANCELLED: Execution was manually cancelled by the user
- PENDING: Queued for async execution (not yet started)
- RUNNING: Currently executing
How Status is Determined
Section titled “How Status is Determined”SUCCESS:
- No exceptions raised
- Workflow/script completes normally
- Returns any value (or no return)
FAILED:
- Any uncaught exception is raised
- Execution terminates due to error
- Includes both technical errors and user-facing errors
COMPLETED_WITH_ERRORS:
- Workflow explicitly returns
{"success": False, ...} - Use this when you want to indicate failure without raising an exception
@workflow(name="process_customer")async def process_customer(context: ExecutionContext, customer_id: str): customer = await get_customer(customer_id)
if not customer: # Explicit failure result return {"success": False, "error": "Customer not found"}
# Process customer... return {"success": True, "customer": customer}Error Types
Section titled “Error Types”Bifrost provides different exception types for different error scenarios:
UserError
Section titled “UserError”Purpose: Errors that should be displayed to end users.
Use UserError when you want to show a specific error message to users (not just platform admins). These are validation errors, business logic failures, or any error that users should see and understand.
from bifrost import UserError, workflow, ExecutionContext
@workflow(name="create_license")async def create_license(context: ExecutionContext, license_key: str): if not license_key: raise UserError("License key is required")
if not is_valid_format(license_key): raise UserError("Invalid license key format. Expected: XXXX-XXXX-XXXX")
customer = await get_customer_by_license(license_key) if not customer: raise UserError(f"No customer found with license key: {license_key}")
# Continue processing...What users see:
- Regular users: See your error message exactly as written
- Platform admins: See your error message plus full technical details
Standard Python Exceptions
Section titled “Standard Python Exceptions”Purpose: Technical/internal errors that should be hidden from regular users.
Use standard Python exceptions (ValueError, RuntimeError, etc.) for technical errors, bugs, or unexpected failures that users shouldn’t see.
@workflow(name="sync_data")async def sync_data(context: ExecutionContext, api_endpoint: str): # Technical error - hidden from regular users if not api_endpoint.startswith('https://'): raise ValueError("API endpoint must use HTTPS")
response = await call_external_api(api_endpoint)
if response.status_code == 500: # Internal server error - hide details from users raise RuntimeError(f"API returned 500: {response.text}")
return response.dataWhat users see:
- Regular users: Generic message: “An error occurred during execution”
- Platform admins: Full exception details including traceback
WorkflowError Variants
Section titled “WorkflowError Variants”These are specialized exceptions for internal Bifrost operations:
from bifrost import ValidationError, IntegrationError, ConfigurationError
# Validation failuresraise ValidationError("Invalid parameter configuration")
# External integration failuresraise IntegrationError("Failed to connect to Microsoft Graph API")
# Configuration issuesraise ConfigurationError("Missing required configuration: api_key")Logging vs Exceptions
Section titled “Logging vs Exceptions”Using logger.error()
Section titled “Using logger.error()”Logger messages are for informational purposes and don’t change execution status:
import loggingfrom bifrost import workflow, ExecutionContext
logger = logging.getLogger(__name__)
@workflow(name="bulk_process")async def bulk_process(context: ExecutionContext, items: list[str]): results = []
for item in items: try: result = await process_item(item) results.append(result) except Exception as e: # Log the error but continue processing logger.error(f"Failed to process item {item}: {e}") continue
# Execution still completes with SUCCESS return {"processed": len(results), "results": results}- Execution status: SUCCESS (no exceptions raised)
- User sees: All log messages including errors
- Use when: Errors are recoverable or partial failures are acceptable
Raising Exceptions
Section titled “Raising Exceptions”Exceptions terminate execution with FAILED status:
@workflow(name="critical_process")async def critical_process(context: ExecutionContext, customer_id: str): customer = await get_customer(customer_id)
if not customer: # This terminates execution immediately raise UserError(f"Customer {customer_id} not found")
# This code never runs if customer is not found return await process_customer(customer)- Execution status: FAILED
- Remaining code: Does not execute
- Use when: Error is fatal and execution cannot continue
Best Practices
Section titled “Best Practices”1. Choose the Right Error Type
Section titled “1. Choose the Right Error Type”# ✅ User-facing validation errorif not email_is_valid(email): raise UserError("Please provide a valid email address")
# ✅ Technical error (hidden from users)if api_response.status_code >= 500: raise RuntimeError(f"Upstream API error: {api_response.status_code}")
# ✅ Recoverable error (log and continue)try: send_notification(user)except Exception as e: logger.error(f"Failed to send notification: {e}") # Continue execution2. Provide Helpful Error Messages
Section titled “2. Provide Helpful Error Messages”# ❌ Vagueraise UserError("Invalid input")
# ✅ Specific and actionableraise UserError("License key must be 19 characters in format: XXXXX-XXXXX-XXXXX-XXXX")3. Use logger.error() for Non-Fatal Issues
Section titled “3. Use logger.error() for Non-Fatal Issues”@workflow(name="sync_all_customers")async def sync_all_customers(context: ExecutionContext): customers = await get_customers() failed = []
for customer in customers: try: await sync_customer(customer) except Exception as e: logger.error(f"Failed to sync customer {customer.id}: {e}") failed.append(customer.id)
if failed: # Return with explicit error status but don't crash return { "success": False, "message": f"Failed to sync {len(failed)} customers", "failed_ids": failed }
return {"success": True, "synced": len(customers)}4. Add Context to Errors
Section titled “4. Add Context to Errors”try: result = await complex_operation(data)except ValueError as e: # Add context about what was being done raise RuntimeError(f"Failed to process customer data for {customer.id}: {e}") from eDebugging Errors
Section titled “Debugging Errors”For Platform Admins
Section titled “For Platform Admins”When viewing execution results as a platform admin, you’ll see:
- Full error messages and exception types
- Complete stack traces in the logs
- All captured variables at the time of failure
- Integration call history
For Regular Users
Section titled “For Regular Users”Regular users see:
- UserError messages (exactly as written)
- Generic message for other exceptions: “An error occurred during execution”
- Logger output (info, warning, error messages)
- Filtered logs without technical stack traces
Error Visibility Summary
Section titled “Error Visibility Summary”| Error Type | Regular Users | Platform Admins |
|---|---|---|
UserError |
See full message | See full message + traceback |
ValueError, RuntimeError, etc. |
“An error occurred during execution” | See full message + traceback |
WorkflowError variants |
“An error occurred during execution” | See full message + traceback |
logger.error() |
See message | See message |
logger.warning() |
See message | See message |
logger.info() |
See message | See message |
Example: Comprehensive Error Handling
Section titled “Example: Comprehensive Error Handling”import loggingfrom bifrost import UserError, workflow, ExecutionContext
logger = logging.getLogger(__name__)
@workflow( name="create_customer_license", description="Create a new customer and provision license")async def create_customer_license( context: ExecutionContext, customer_name: str, email: str, license_type: str): # Validate inputs - show validation errors to users if not customer_name or len(customer_name) < 2: raise UserError("Customer name must be at least 2 characters")
if not '@' in email: raise UserError("Invalid email address format")
if license_type not in ['standard', 'premium', 'enterprise']: raise UserError(f"Invalid license type: {license_type}. Choose: standard, premium, enterprise")
try: # Check for existing customer existing = await find_customer_by_email(email) if existing: raise UserError(f"Customer with email {email} already exists")
# Create customer logger.info(f"Creating customer: {customer_name}") customer = await create_customer(customer_name, email) logger.info(f"Customer created with ID: {customer.id}")
# Provision license logger.info(f"Provisioning {license_type} license...") license = await provision_license(customer.id, license_type) logger.info(f"License provisioned: {license.key}")
# Send welcome email (non-fatal if fails) try: await send_welcome_email(email, license.key) logger.info("Welcome email sent") except Exception as e: logger.error(f"Failed to send welcome email: {e}") # Continue execution - email failure isn't fatal
return { "success": True, "customer_id": customer.id, "license_key": license.key, "message": f"Customer {customer_name} created successfully" }
except UserError: # Re-raise UserErrors as-is raise except Exception as e: # Unexpected technical error - log details and show generic message to users logger.error(f"Unexpected error creating customer: {e}", exc_info=True) raise RuntimeError(f"Failed to create customer: {type(e).__name__}") from e