Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.circuit.org/llms.txt

Use this file to discover all available pages before exploring further.

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
}

​
Checking Results

Always check success before using data: 
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

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

​
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 CodeCauseSolution
QUOTE_TIMEOUTQuote request timed outRetry after a brief delay
ALL_ENGINES_FAILEDEvery routing engine returned an errorCheck input parameters; the route may not be available
NO_COMPATIBLE_ENGINESNo engine supports this token pair or routeVerify token addresses and network IDs
ENGINE_API_ERRORUpstream routing engine returned an errorRetry; if persistent, the engine may be temporarily down
PRICE_IMPACT_TOO_HIGHPrice impact exceeds acceptable thresholdReduce swap amount or increase slippage tolerance
INSUFFICIENT_BALANCEWallet balance too low for this swapCheck positions before quoting
INTERNAL_ERRORUnexpected internal errorLog 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 CodeCauseSolution
ORDERBOOK_NOT_FOUNDNo orderbook for the given tokenVerify tokenId from Polymarket
MARKET_NOT_FOUNDMarket does not existCheck that the market hasn’t been resolved or removed
TOKEN_NOT_IN_MARKETToken ID not associated with marketUse correct tokenId for the market
INSUFFICIENT_LIQUIDITYNot enough liquidity to fill orderReduce order size or wait for more liquidity
INSUFFICIENT_BALANCEWallet pUSD balance too low for this orderCheck balances before placing orders
ORDER_REJECTEDOrder was rejected by the exchangeCheck order parameters (size, side)
UPSTREAM_API_ERRORPolymarket API returned an errorRetry; check Polymarket status
UPSTREAM_HTTP_ERRORHTTP error from PolymarketRetry with backoff
UPSTREAM_INVALID_RESPONSEUnexpected response format from PolymarketLikely a temporary API issue; retry
NETWORK_ERRORNetwork connectivity issueRetry with backoff
CREDENTIALS_ERRORInvalid or missing API credentialsEnsure session is active and wallet is valid
INTERNAL_ERRORUnexpected internal errorLog 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)
This applies to all transacting methods: signAndSend, swap.execute, polymarket.marketOrder, and polymarket.redeemPositions.

​
General Error Patterns

ErrorCauseSolution
”Key not found”Memory key doesn’t existCheck if key exists first or handle missing keys
”Invalid request”Bad parameters to SDK methodValidate inputs before calling SDK methods
”Transaction failed”Insufficient balance/gas or revertCheck balances via getCurrentPositions() before transactions

​
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

​
See Also

  • Troubleshooting — Common issues and solutions for CLI, SDK, and platform-specific problems
  • Logging — Log errors with error: true so they appear in the UI