Error Handling

All SDK methods return response objects with consistent `success`/`error` patterns.

Response Structure

All SDK methods return response objects:

TypeScript

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

Python

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 || result.errorMessage}`, { error: true });
}

Python

Uncaught Exceptions

Uncaught exceptions in run or unwind are caught by the SDK. The execution is marked as failed and the error is logged. You don't need to wrap SDK method calls in try/catch blocks unless you need to handle for a specific error.

TypeScript

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

Python

When to Use Try/Catch

Use try/catch for:

• Custom agent logic that throws

• Operations requiring custom recovery

• Parsing/calculations with external data

Don't use try/catch for:

• SDK method calls (use .success checks)

• Top-level errors (auto-caught by SDK)

Common Error Patterns - (More details to come!)

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 getCurrentPositions() before transactions

Best Practices

1. Always check success before using data

2. Log errors with error: true / error=True for visibility

3. Return early on errors instead of continuing

4. Don't wrap everything in try/catch - the SDK handles top-level errors

5. Validate inputs before making SDK calls