Skip to content
Bifrost Docs

Error Handling

Understanding error handling and execution statuses in Bifrost

Every workflow and script execution goes through various states and can complete with different statuses:

  • 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

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}

Bifrost provides different exception types for different error scenarios:

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

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.data

What users see:

  • Regular users: Generic message: “An error occurred during execution”
  • Platform admins: Full exception details including traceback

These are specialized exceptions for internal Bifrost operations:

from bifrost import ValidationError, IntegrationError, ConfigurationError
# Validation failures
raise ValidationError("Invalid parameter configuration")
# External integration failures
raise IntegrationError("Failed to connect to Microsoft Graph API")
# Configuration issues
raise ConfigurationError("Missing required configuration: api_key")

Logger messages are for informational purposes and don’t change execution status:

import logging
from 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

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
# ✅ User-facing validation error
if 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 execution
# ❌ Vague
raise UserError("Invalid input")
# ✅ Specific and actionable
raise 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)}
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 e

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

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 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
import logging
from 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