Error Handling

Handle errors in the AveniECA API

The AveniECA API returns structured error responses and HTTP status codes to help you handle failures gracefully.

Error Response Model

When an error occurs, the API returns an Error object:

from avenieca.api.model import Error

@dataclass
class Error(Base):
    errors: List[str]  # List of error messages

Response Pattern

All API methods return a tuple of (response, status_code):

response, status = eca.ess.get_one(module_id="example", db_id=1)

if status == 200:
    # Success - response is the expected model
    print(f"ESS ID: {response.id}")
else:
    # Error - response is an Error object or raw response
    if isinstance(response, Error):
        print(f"Errors: {response.errors}")
    else:
        print(f"Error: {response}")

HTTP Status Codes

Success Codes

• 200 OK - Request succeeded (GET, PATCH, PUT)
• 201 Created - Resource created successfully (POST)

Error Codes

• 400 Bad Request - Invalid request parameters or data
• 401 Unauthorized - Authentication failed or missing
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Common Errors

Authentication Errors

import os
from avenieca.api.eca import ECA
from avenieca.api.model import Config

config = Config(
    uri="http://localhost:2580/v1",
    username="invalid",
    password="wrong"
)

try:
    eca = ECA(config)
except Exception as e:
    print(f"Authentication failed: {e}")
    # Handle authentication failure

Resource Not Found

res, status = eca.ess.get_one(module_id="example", db_id=999999)

if status == 404:
    print("ESS not found")
    # Handle missing resource
elif status == 200:
    print(f"Found ESS: {res.id}")

Invalid Data

from avenieca.api.model import ESSInsert, Error

# Missing required fields
incomplete_ess = ESSInsert(
    module_id="",  # Invalid empty module_id
    state=[],
    valence=0.0
)

res, status = eca.ess.create(data=incomplete_ess)

if status != 201:
    if isinstance(res, Error):
        print("Validation errors:")
        for error in res.errors:
            print(f"  - {error}")

Aggregate Errors

When creating or updating aggregates, you may receive an AggregateError:

from avenieca.api.model import AggregateError, Error

res, status = eca.ess.create(data=aggregate_ess)

if status != 201:
    if isinstance(res, AggregateError):
        print("Aggregate validation errors:")
        if res.field_length_errors:
            print(f"Field length errors: {res.field_length_errors}")
        if res.module_id_position:
            print(f"Module ID position errors: {res.module_id_position}")
        if res.invalid_ess_db_ids:
            print(f"Invalid ESS IDs: {res.invalid_ess_db_ids}")
    elif isinstance(res, Error):
        print(f"Errors: {res.errors}")

Error Handling Patterns

Basic Pattern

def safe_create_ess(eca, ess_data):
    """Safely create ESS with error handling."""
    res, status = eca.ess.create(data=ess_data)
    
    if status == 201:
        return res
    else:
        if isinstance(res, Error):
            raise ValueError(f"Failed to create ESS: {res.errors}")
        else:
            raise ValueError(f"Unexpected error: {res}")

try:
    ess = safe_create_ess(eca, ess_data)
    print(f"Created ESS {ess.id}")
except ValueError as e:
    print(f"Error: {e}")

Retry Pattern

import time
from typing import Optional

def get_ess_with_retry(
    eca,
    module_id: str,
    db_id: int,
    max_retries: int = 3
) -> Optional[ESSResponse]:
    """Get ESS with retry logic."""
    for attempt in range(max_retries):
        res, status = eca.ess.get_one(module_id=module_id, db_id=db_id)
        
        if status == 200:
            return res
        elif status == 404:
            return None  # Resource doesn't exist
        elif status >= 500:
            # Server error - retry
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
        else:
            # Client error - don't retry
            return None
    
    return None

ress = get_ess_with_retry(eca, "air_conditioner", 1)
if ess:
    print(f"Retrieved ESS {ess.id}")
else:
    print("Failed to retrieve ESS")

Validation Pattern

from avenieca.api.model import ESSInsert, Error

def validate_and_create_ess(eca, ess_data: ESSInsert):
    """Validate ESS data before creation."""
    # Pre-validation
    if not ess_data.module_id:
        raise ValueError("module_id is required")
    if not ess_data.state:
        raise ValueError("state cannot be empty")
    
    # Create
    res, status = eca.ess.create(data=ess_data)
    
    # Handle response
    if status == 201:
        return res
    elif isinstance(res, Error):
        raise ValueError(f"API errors: {', '.join(res.errors)}")
    else:
        raise ValueError(f"Unexpected error (status {status})")

try:
    ess = validate_and_create_ess(eca, ess_data)
    print(f"Created ESS {ess.id}")
except ValueError as e:
    print(f"Validation failed: {e}")

Best Practices

1. Always check status codes - Don’t assume success
2. Handle specific errors - Use isinstance() to check error types
3. Log errors - Record errors for debugging
4. Validate input - Check data before sending to API
5. Use retries for server errors - Implement exponential backoff
6. Don’t retry client errors - 4xx errors won’t succeed on retry
7. Provide user feedback - Convert errors to user-friendly messages

Complete Example

import os
import logging
from avenieca.api.eca import ECA
from avenieca.api.model import Config, ESSInsert, Error, AggregateError

# Setup logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Initialize client with error handling
try:
    config = Config(
        uri="http://localhost:2580/v1",
        username=os.getenv("USERNAME"),
        password=os.getenv("PASSWORD")
    )
    eca = ECA(config)
    logger.info("Successfully initialized ECA client")
except Exception as e:
    logger.error(f"Failed to initialize ECA: {e}")
    raise

# Create ESS with comprehensive error handling
ess_data = ESSInsert(
    module_id="air_conditioner",
    state=[25.0],
    valence=10.0,
    score=5
)

res, status = eca.ess.create(data=ess_data)

if status == 201:
    logger.info(f"Created ESS {res.id}")
    print(f"Success: ESS {res.id} created")
elif isinstance(res, AggregateError):
    logger.error(f"Aggregate validation failed: {res.__dict__}")
    print("Aggregate validation errors - check logs")
elif isinstance(res, Error):
    logger.error(f"API errors: {res.errors}")
    print(f"Failed: {', '.join(res.errors)}")
else:
    logger.error(f"Unexpected error (status {status}): {res}")
    print(f"Failed with status {status}")