Error Handling

All SDK methods return a consistent response pattern. For method-specific errors, see the "Common Errors" section in each method's documentation.

Response Structure

TypeScript:

{
  success: boolean;
  data?: any;
  error?: string;
  errorMessage?: string;
  errorDetails?: object;
}

Python:

{
  success: bool
  data: any | None
  error: str | None
  error_message: str | None  # Note: Python uses snake_case
  error_details: dict | None
}

The log() method doesn't include a data field since it has no return value.

Checking Results

Always check success before using data:

TypeScript:

const result = await agent.memory.get("key");

if (result.success && result.data) {
  // Safe to use result.data
  await agent.log(`Value: ${result.data.value}`);
} else {
  // Handle error
  await agent.log(`Error: ${result.error}`, { error: true });
}

Python:

result = agent.memory.get("key")

if result.success and result.data:
    # Safe to use result.data
    agent.log(f"Value: {result.data.value}")
else:
    # Handle error
    agent.log(f"Error: {result.error}", error=True)

Uncaught Exceptions

The SDK automatically handles uncaught exceptions in your run and unwind functions:

TypeScript:

async function run(agent: AgentContext): Promise<void> {
  // This typo will be caught and logged automatically
  await agent.memmory.set("key", "value");  // TypeError
}

Python:

def run(agent: AgentContext) -> None:
    # This typo will be caught and logged automatically
    agent.memmory.set("key", "value")  # Typo - auto-caught

No try/catch needed, and the agent won't crash. Circuit will mark the execution as failed and log the error.

When to Use Try/Catch

Use Try/Catch	Don't Need Try/Catch
Custom business logic that throws	SDK method calls (use .success checks)
Operations requiring custom recovery	Top level errors (auto-caught by SDK)
Parsing/calculations with external data

Common Error Patterns

Error Type	Cause	Solution
"Key not found"	Memory key doesn't exist	Check if key exists first or handle missing keys
"Invalid request"	Bad parameters	Validate inputs before calling SDK methods
"Quote failed"	Amount too small, no liquidity	Increase amount, adjust slippage, or validate quote
"Transaction failed"	Insufficient balance/gas	Check balances via currentPositions before transactions

Best Practices

1. Always check success before using data

2. Log errors with { error: true } for visibility

3. Fail gracefully - return early on errors instead of continuing

4. Don't wrap everything in try/catch - the SDK handles this

5. Validate inputs before making SDK calls