Error Codes Reference

Complete reference of all error codes in StrataRouter Core and Runtime.

Core Errors

Route Errors

RouteNotFound

Code: ROUTE_NOT_FOUND
Severity: Low
Recoverable: Yes

Route with specified ID was not found in the router.

Error::RouteNotFound { route_id: String }

Common Causes: - Route ID typo - Route not added to router - Route removed after routing

Solution:

# Check if route exists
if route_id in router.list_routes():
    result = router.route(query, embedding)

---

NoRoutes

Code: NO_ROUTES
Severity: Medium
Recoverable: Yes

Router has no routes configured.

Error::NoRoutes

Solution:

# Add routes before using router
router.add_route(Route("billing"))
router.add_route(Route("support"))
router.build_index(embeddings)

---

Index Errors

IndexNotBuilt

Code: INDEX_NOT_BUILT
Severity: Medium
Recoverable: Yes

Attempted to route before building the index.

Error::IndexNotBuilt

Solution:

# Build index before routing
router.build_index(embeddings)
result = router.route(query, embedding)

---

DimensionMismatch

Code: DIMENSION_MISMATCH
Severity: Low
Recoverable: Yes

Embedding dimension doesn't match router configuration.

Error::DimensionMismatch {
    expected: usize,
    actual: usize,
}

Common Causes: - Wrong embedding model - Configuration mismatch - Data corruption

Solution:

# Ensure consistent dimensions
config = RouterConfig(dimension=384)  # Match your embeddings
router = Router(config)

# Verify embedding dimension
assert len(embedding) == 384

---

Input Errors

InvalidInput

Code: INVALID_INPUT
Severity: Low
Recoverable: Yes

Invalid input provided to a function.

Error::InvalidInput { message: String }

Common Causes: - Empty query text - Empty embedding - Invalid route configuration - Out-of-range parameters

Examples:

# Empty query
router.route("", embedding)  # Error: InvalidInput

# Empty embedding
router.route("query", [])  # Error: InvalidInput

# Invalid route
route = Route("")  # Error: Route ID cannot be empty
route.validate()

# Invalid config
config = RouterConfig(dimension=0)  # Error: Dimension must be positive

---

System Errors

Io

Code: IO_ERROR
Severity: Critical
Recoverable: No

File system I/O error occurred.

Error::Io(std::io::Error)

Common Causes: - File not found - Permission denied - Disk full - Network file system issues

---

Serialization

Code: SERIALIZATION_ERROR
Severity: High
Recoverable: No

Failed to serialize or deserialize data.

Error::Serialization(serde_json::Error)

Common Causes: - Corrupted data - Schema version mismatch - Invalid JSON/TOML

---

Unknown

Code: UNKNOWN_ERROR
Severity: Critical
Recoverable: No

Unknown or unexpected error occurred.

Error::Unknown { message: String }

---

Runtime Errors

Execution Errors

ExecutionFailed

Code: EXECUTION_FAILED
HTTP Status: 500

Workflow execution failed.

{
  "error": "ExecutionFailed",
  "message": "Step 3 failed: Connection timeout",
  "execution_id": "exec_abc123",
  "step_index": 3
}

Solution: - Check workflow definition - Verify external service availability - Review execution logs

---

ExecutionTimeout

Code: EXECUTION_TIMEOUT
HTTP Status: 504

Execution exceeded timeout limit.

{
  "error": "ExecutionTimeout",
  "message": "Execution timeout after 60s",
  "execution_id": "exec_abc123",
  "timeout_seconds": 60
}

Solution:

# Increase timeout
config = RuntimeConfig(execution_timeout=120)  # 2 minutes
bridge = CoreRuntimeBridge(config)

---

Resource Errors

RateLimitExceeded

Code: RATE_LIMIT_EXCEEDED
HTTP Status: 429

Rate limit exceeded for tenant or user.

{
  "error": "RateLimitExceeded",
  "message": "Rate limit: 100 req/s exceeded",
  "limit": 100,
  "current": 150,
  "retry_after": 5
}

Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
Retry-After: 5

---

QuotaExceeded

Code: QUOTA_EXCEEDED
HTTP Status: 402

Usage quota exceeded.

{
  "error": "QuotaExceeded",
  "message": "Daily execution quota (1000) exceeded",
  "quota_type": "daily_executions",
  "limit": 1000,
  "used": 1000
}

---

Provider Errors

ProviderError

Code: PROVIDER_ERROR
HTTP Status: 502

LLM provider returned an error.

{
  "error": "ProviderError",
  "provider": "openai",
  "message": "API rate limit exceeded",
  "provider_code": "rate_limit_exceeded"
}

Retry Behavior: - Automatic retry with exponential backoff - Falls back to secondary provider if configured - Circuit breaker after 5 consecutive failures

---

Cache Errors

CacheError

Code: CACHE_ERROR
HTTP Status: 500

Cache operation failed.

{
  "error": "CacheError",
  "message": "Redis connection failed",
  "operation": "get"
}

Behavior: - Cache errors don't fail requests - Falls back to direct execution - Logged for investigation

---

Error Handling Best Practices

Python

from stratarouter import Router, Error

try:
    result = router.route(query, embedding)
except Error.DimensionMismatch as e:
    print(f"Embedding dimension {e.actual} doesn't match expected {e.expected}")
    # Fix embedding dimension
except Error.IndexNotBuilt:
    print("Build index first")
    router.build_index(embeddings)
    result = router.route(query, embedding)
except Error.InvalidInput as e:
    print(f"Invalid input: {e.message}")
    # Validate input
except Error as e:
    if e.is_recoverable():
        print(f"Recoverable error: {e}")
        # Retry or fix input
    else:
        print(f"System error: {e}")
        # Log and alert
        raise

Rust

use stratarouter_core::{Router, Error};

match router.route(query, &embedding) {
    Ok(result) => {
        println!("Route: {}", result.route_id);
    }
    Err(Error::DimensionMismatch { expected, actual }) => {
        eprintln!("Dimension mismatch: expected {}, got {}", expected, actual);
    }
    Err(Error::IndexNotBuilt) => {
        eprintln!("Index not built");
        router.build_index(embeddings)?;
    }
    Err(e) if e.is_recoverable() => {
        eprintln!("Recoverable error: {}", e);
    }
    Err(e) => {
        eprintln!("Critical error: {}", e);
        return Err(e);
    }
}

Runtime

from stratarouter_runtime import CoreRuntimeBridge, RuntimeError

try:
    result = await bridge.execute(decision, context)
except RuntimeError.RateLimitExceeded as e:
    print(f"Rate limit exceeded, retry after {e.retry_after}s")
    await asyncio.sleep(e.retry_after)
    result = await bridge.execute(decision, context)
except RuntimeError.QuotaExceeded as e:
    print(f"Quota exceeded: {e.quota_type}")
    # Upgrade plan or wait for reset
except RuntimeError.ProviderError as e:
    print(f"Provider {e.provider} error: {e.message}")
    # Try alternative provider
except RuntimeError as e:
    print(f"Runtime error: {e}")
    # Log and handle

Error Severity Levels

Severity	Description	Action
Low	User input error	Return error to user
Medium	Operation cannot proceed	Log and return error
High	Data inconsistency	Log, alert, return error
Critical	System error	Log, alert, escalate

HTTP Status Code Mapping

Error	Status Code	Retry?
InvalidInput	400	No
QuotaExceeded	402	No
RateLimitExceeded	429	Yes, with backoff
ExecutionFailed	500	Yes
ProviderError	502	Yes, different provider
ExecutionTimeout	504	Yes, with longer timeout

Monitoring Errors

Metrics

# Error rate
stratarouter_errors_total{type="InvalidInput",severity="low"}

# Error rate by endpoint
stratarouter_http_errors_total{endpoint="/route",status="400"}

# Provider errors
stratarouter_provider_errors_total{provider="openai",code="rate_limit"}

Alerts

# High error rate
- alert: HighErrorRate
  expr: rate(stratarouter_errors_total[5m]) > 10
  annotations:
    summary: High error rate detected

# Provider failures
- alert: ProviderDown
  expr: rate(stratarouter_provider_errors_total[5m]) > 5
  annotations:
    summary: LLM provider experiencing issues

Support

For persistent errors:

1. Check Troubleshooting Guide
2. Search GitHub Issues
3. Ask on Discord
4. Contact support: support@inteleionlabs.com