Errors

Error Handling

Error Classification

The OpenFlow Protocol defines a standardized error classification system organized by category:

Validation Errors (1000-1999)

Code	Error Type	Description	Common Causes
1001	`SCHEMA_VALIDATION_ERROR`	Flow does not conform to required schema	Missing required fields, incorrect JSON structure
1002	`MISSING_REQUIRED_FIELD`	Required property is missing	Incomplete flow definition
1003	`INVALID_TYPE`	Property value does not match expected type	String provided where number expected
1004	`INVALID_FORMAT`	Property value format is incorrect	Invalid email, URL, or regex format
1005	`DUPLICATE_IDENTIFIER`	Non-unique ID found within scope	Duplicate node IDs, variable names
1006	`CIRCULAR_DEPENDENCY`	Circular reference detected in flow	Node A depends on Node B which depends on Node A
1007	`MISSING_DEPENDENCY`	Referenced variable or node not found	Typo in variable reference
1008	`FORWARD_REFERENCE`	Invalid reference to future node	Node references another node that executes later

Execution Errors (2000-2999)

Code	Error Type	Description	Recovery Actions
2001	`NODE_EXECUTION_ERROR`	Generic node execution failure	Check node configuration, retry
2002	`PROVIDER_ERROR`	External provider service error	Check provider status, credentials
2003	`TIMEOUT_ERROR`	Operation exceeded configured timeout	Increase timeout, optimize query
2004	`RATE_LIMIT_ERROR`	Provider rate limit exceeded	Implement backoff, upgrade plan
2005	`AUTHENTICATION_ERROR`	Provider authentication failure	Verify credentials, check permissions
2006	`PERMISSION_ERROR`	Insufficient permissions for operation	Review access rights
2007	`RESOURCE_ERROR`	Insufficient system resources	Scale system, optimize memory usage
2008	`NETWORK_ERROR`	Network connectivity issue	Check connection, retry

Runtime Errors (3000-3999)

Code	Error Type	Description	Resolution
3001	`VARIABLE_RESOLUTION_ERROR`	Unable to resolve variable reference	Check variable exists, correct scope
3002	`TYPE_CONVERSION_ERROR`	Type conversion failure	Validate input types
3003	`OUTPUT_VALIDATION_ERROR`	Node output doesn't match schema	Review node implementation
3004	`CONCURRENCY_ERROR`	Concurrency limit exceeded	Adjust global limits
3005	`MEMORY_ERROR`	Out of memory condition	Optimize flow, increase memory
3006	`FILE_SYSTEM_ERROR`	File operation failure	Check file permissions, disk space

System Errors (4000-4999)

Code	Error Type	Description	Admin Actions
4001	`INTERNAL_ERROR`	Unexpected system error	Contact support, check logs
4002	`CONFIGURATION_ERROR`	Invalid system configuration	Review configuration files
4003	`VERSION_ERROR`	Protocol version mismatch	Update implementation
4004	`PLUGIN_ERROR`	Extension/plugin failure	Update/reinstall plugins

Error Response Format

All errors MUST follow this standardized format:

Field	Type	Required	Description	Example
`code`	integer	✅	Error code (1000-4999)	`2003`
`type`	string	✅	Error type identifier	`TIMEOUT_ERROR`
`message`	string	✅	Human-readable description	"Operation exceeded 30s timeout"
`details`	object	❌	Additional error context	`{"timeout_ms": 30000, "actual_ms": 45000}`
`node_id`	string	❌	Failing node identifier	`llm_processor_1`
`flow_id`	string	❌	Flow execution identifier	`20240115_143022_001`
`timestamp`	string	✅	ISO 8601 timestamp	`2024-01-15T14:30:22.123Z`
`stack_trace`	string	❌	Debug stack trace	`Error at line 42...`
`retry_after`	integer	❌	Retry delay in seconds	`60`

{
  "error": {
    "code": 2003,
    "type": "TIMEOUT_ERROR",
    "message": "LLM request exceeded configured timeout of 30 seconds",
    "details": {
      "timeout_ms": 30000,
      "actual_duration_ms": 45000,
      "provider": "openai",
      "model": "gpt-4"
    },
    "node_id": "llm_processor_1",
    "flow_id": "20240115_143022_001",
    "timestamp": "2024-01-15T14:30:22.123Z",
    "retry_after": 60
  }
}

Error Propagation

Error Level	Behavior	Impact	Automatic Recovery
Node-Level	Stops flow execution immediately	Current flow fails	No retry by default
Flow-Level	Prevents execution from starting	Flow rejected	Validation must pass
Provider-Level	May trigger retry logic	Temporary failure	Configurable retry policies
System-Level	Requires admin intervention	Service degradation	Manual recovery required

Recovery Mechanisms

Mechanism	Purpose	Configuration	Use Cases
Retry Policies	Automatic retry with backoff	`max_retries`, `backoff_strategy`	Transient network errors
Circuit Breakers	Prevent cascade failures	`failure_threshold`, `recovery_timeout`	Provider outages
Fallback Providers	Alternative service endpoints	`fallback_provider_id`	High availability
Graceful Degradation	Reduced functionality	Feature flags	Partial service issues

Errors

On this page