Documentation Index
Fetch the complete documentation index at: https://mintlify.com/aveni-hub/avenieca-python/llms.txt
Use this file to discover all available pages before exploring further.
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
- Always check status codes - Don’t assume success
- Handle specific errors - Use isinstance() to check error types
- Log errors - Record errors for debugging
- Validate input - Check data before sending to API
- Use retries for server errors - Implement exponential backoff
- Don’t retry client errors - 4xx errors won’t succeed on retry
- 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}")