Error Handling

Use these patterns to handle failures gracefully - checking success before using data, logging errors for visibility in the UI, and matching specific error codes when you need different recovery logic per failure type.

Response Structure

All SDK methods return response objects:

{
    success: bool
    data: any | None
    error: str | None
}

{
  success: boolean;
  data?: any;
  error?: string;
}

Checking Results

Always check success before using data:

result = agent.memory.get("key")
if not result.success:
    # A real failure (auth, bad scope, store unavailable)
    agent.log(f"Error: {result.error}", error=True)
elif result.data and result.data.value is not None:
    agent.log(f"Value: {result.data.value}")
else:
    # A miss is not an error - the key is simply not set
    agent.log("Key not set yet")

const result = await agent.memory.get("key");
if (!result.success) {
  // A real failure (auth, bad scope, store unavailable)
  await agent.log(`Error: ${result.error}`, { error: true });
} else if (result.data?.value != null) {
  await agent.log(`Value: ${result.data.value}`);
} else {
  // A miss is not an error - the key is simply not set
  await agent.log("Key not set yet");
}

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.

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

    # No try/except needed

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
}

Correlating Transport Failures

When an engine request fails at the HTTP, network, timeout, or run-deadline boundary, the SDK error includes the request ID sent to Circuit. The rendered error message also ends with (requestId=...), so the ID survives in normal agent logs. In custom error handling, read error.request_id in Python or error.requestId in TypeScript and include it when reporting the failure; it is the lookup key Circuit operators use to find the matching service logs.

When to Use Try/Catch

Only use try/catch for your own logic that might throw (parsing, calculations with external data, custom recovery). Don’t use it for SDK method calls - just check .success instead.

Swap Error Codes

Swap methods (agent.swap.quote(), agent.swap.execute()) return typed error codes in the error field:

Error Code	Cause	Solution
`QUOTE_TIMEOUT`	Quote request timed out	Retry after a brief delay
`ALL_ENGINES_FAILED`	Every routing engine returned an error	Check input parameters; the route may not be available
`NO_COMPATIBLE_ENGINES`	No engine supports this token pair or route	Verify token addresses and network IDs
`ENGINE_API_ERROR`	Upstream routing engine returned an error	Retry; if persistent, the engine may be temporarily down
`PRICE_IMPACT_TOO_HIGH`	Price impact exceeds acceptable threshold	Reduce swap amount or increase slippage tolerance
`INSUFFICIENT_BALANCE`	Wallet balance too low for this swap	Check positions before quoting
`QUOTE_STALE`	Quote expired before execution	Request a fresh quote and execute it promptly
`INTERNAL_ERROR`	Unexpected internal error	Log and retry; contact support if persistent

Hyperliquid Error Codes

Hyperliquid methods (agent.platforms.hyperliquid.*) return error messages in the error field. See Hyperliquid: Common Errors for the full table.

Polymarket Error Codes

Polymarket methods (agent.platforms.polymarket.*) return typed error codes:

Error Code	Cause	Solution
`ORDERBOOK_NOT_FOUND`	No orderbook for the given token	Verify tokenId from Polymarket
`MARKET_NOT_FOUND`	Market does not exist	Check that the market hasn’t been resolved or removed
`TOKEN_NOT_IN_MARKET`	Token ID not associated with market	Use correct tokenId for the market
`INSUFFICIENT_LIQUIDITY`	Not enough liquidity to fill order	Reduce order size or wait for more liquidity
`INSUFFICIENT_BALANCE`	Wallet pUSD balance too low for this order	Check balances before placing orders
`ORDER_REJECTED`	Order was rejected by the exchange	Check order parameters (size, side)
`WALLET_NOT_GRANDFATHERED`	Polymarket rejects orders from wallets with no prior Polymarket trading history (only grandfathered wallets may trade)	Permanent for the wallet - do not retry; run the agent on a wallet that has traded on Polymarket before
`POSITIONS_NOT_REDEEMABLE`	None of the requested positions can be redeemed (market not resolved, or tokens not held); the message lists each skip reason	Only pass tokenIds whose position is `isRedeemable: true`
`UPSTREAM_API_ERROR`	Polymarket API returned an error	Retry; check Polymarket status
`UPSTREAM_HTTP_ERROR`	HTTP error from Polymarket	Retry with backoff
`UPSTREAM_INVALID_RESPONSE`	Unexpected response format from Polymarket	Likely a temporary API issue; retry
`NETWORK_ERROR`	Network connectivity issue	Retry with backoff
`CREDENTIALS_ERROR`	Invalid or missing API credentials	Ensure session is active and wallet is valid
`INTERNAL_ERROR`	Unexpected internal error	Log and retry; contact support if persistent

Transaction Reverts

The server automatically waits for onchain confirmation after broadcasting a transaction. If the transaction was mined but reverted onchain, the response returns success: false with an error message. No SDK-side option is needed.

result = agent.sign_and_send({
    "network": "ethereum:1",
    "request": {
        "to_address": "0x...",
        "data": "0x...",
        "value": "0",
    },
})

if not result.success:
    if result.error and "reverted" in result.error:
        agent.log("Transaction reverted onchain", error=True)
    else:
        agent.log(f"Error: {result.error}", error=True)

const result = await agent.signAndSend({
  network: "ethereum:1",
  request: {
    toAddress: "0x...",
    data: "0x...",
    value: "0",
  },
});

if (!result.success) {
  if (result.error?.includes("reverted")) {
    await agent.log("Transaction reverted onchain", { error: true });
  } else {
    await agent.log(`Error: ${result.error}`, { error: true });
  }
}

This applies to all transacting methods: signAndSend, swap.execute, polymarket.marketOrder, and polymarket.redeemPositions.

General Error Patterns

Error	Cause	Solution
”Invalid request”	Bad parameters to SDK method	Validate inputs before calling SDK methods
”Transaction failed”	Insufficient balance/gas or revert	Check `agent.allocation` and any earlier actions in this invocation

Tips

Always check success before using data
Log errors with error: true / error=True so they show up in the UI
Return early on errors instead of continuing
Validate inputs before making SDK calls
Match against specific error codes when you need different handling per failure type

Getting Started

Core Concepts

Examples

CLI Reference

SDK Reference

Advanced

Response Structure

Checking Results

Uncaught Exceptions

Correlating Transport Failures

When to Use Try/Catch

Swap Error Codes

Hyperliquid Error Codes

Polymarket Error Codes

Transaction Reverts

General Error Patterns

Tips

See Also

​Response Structure

​Checking Results

​Uncaught Exceptions

​Correlating Transport Failures

​When to Use Try/Catch

​Swap Error Codes

​Hyperliquid Error Codes

​Polymarket Error Codes

​Transaction Reverts

​General Error Patterns

​Tips

​See Also

Response Structure

Checking Results

Uncaught Exceptions

Correlating Transport Failures

When to Use Try/Catch

Swap Error Codes

Hyperliquid Error Codes

Polymarket Error Codes

Transaction Reverts

General Error Patterns

Tips

See Also