Error Reference

Error codes, exit codes, and recovery hints for the AgentsWallets CLI.

Error envelope

All errors are returned as JSON on stdout with a consistent structure:

{
  "ok": false,
  "data": null,
  "error": {
    "code": "ERR_INSUFFICIENT_FUNDS",
    "message": "Need 10 USDC, have 2.3",
    "details": { "required": "10", "available": "2.3", "token": "USDC" },
    "recovery_hint": "Top up wallet. Check balance with `aw wallet balance <name>`."
  },
  "meta": { "request_id": "req_abc" }
}

Exit codes

Code	Category	Description
`0`	Success	Command completed successfully
`1`	Business error	Invalid params, policy violation, insufficient balance
`2`	System error	Network, RPC, or third-party failure
`3`	Auth error	Session expired or wrong password

Error codes

Code	Exit	Message	Recovery hint
`ERR_NOT_INITIALIZED`	1	Data store not initialized	Run `aw init` to initialize.
`ERR_NEED_UNLOCK`	3	Session expired or not unlocked	Run `aw unlock` to start a session.
`ERR_AUTH_FAILED`	3	Master password incorrect	Check master password. Run `aw unlock` to retry.
`ERR_INVALID_PARAMS`	1	Invalid command arguments	Check command arguments and input requirements.
`ERR_WALLET_NOT_FOUND`	1	Wallet not found	Check wallet name with `aw wallet list`.
`ERR_MARKET_NOT_FOUND`	1	Market ID not found	Verify market ID with `aw predict markets`.
`ERR_INVALID_AMOUNT`	1	Invalid amount value	Provide a positive numeric amount.
`ERR_INSUFFICIENT_FUNDS`	1	Not enough funds	Top up wallet. Check balance with `aw wallet balance <name>`.
`ERR_DAILY_LIMIT_EXCEEDED`	1	Daily spending limit reached	Wait for daily reset (UTC midnight) or raise limit with `aw policy set`.
`ERR_PER_TX_LIMIT_EXCEEDED`	1	Amount exceeds per-tx limit	Reduce amount or raise per-tx limit with `aw policy set`.
`ERR_TX_COUNT_LIMIT_EXCEEDED`	1	Max transactions per day reached	Wait for daily reset (UTC midnight) or raise max_tx_per_day.
`ERR_APPROVAL_REQUIRED`	1	Amount exceeds approval threshold	Requires human approval or lower `require_approval_above`.
`ERR_IDEMPOTENCY_CONFLICT`	1	Idempotency key already used with different params	Use a new idempotency key or check the original result.
`ERR_RPC_UNAVAILABLE`	2	RPC endpoint unavailable	Check network or set AW_RPC_URL. Retry with `--timeout <ms>`.
`ERR_POLYMARKET_FAILED`	2	Polymarket operation failed	Retry the operation. Check `aw health` for diagnostics.
`ERR_POLYMARKET_AUTH`	2	Polymarket authentication error	Re-run `aw predict approve-set` to refresh approvals.
`ERR_POLYMARKET_TIMEOUT`	2	Polymarket CLI timed out	Increase timeout with `AW_POLY_TIMEOUT_MS` or retry.
`ERR_TX_FAILED`	2	Transaction failed on-chain	Check explorer for details. Retry or adjust gas settings.
`ERR_POLYMARKET_CLI_NOT_FOUND`	2	Polymarket CLI not installed	Install the Polymarket CLI. See prerequisites in Quick Start.
`ERR_OKX_AUTH`	2	OKX API authentication failed	Check OKX API credentials. Run `aw health` for diagnostics.
`ERR_OKX_API_FAILED`	2	OKX API request failed	Retry the operation. Check `aw health` for OKX API status.
`ERR_OKX_TIMEOUT`	2	OKX API request timed out	Retry with backoff. Check network connectivity.
`ERR_OKX_QUOTE_FAILED`	2	Failed to get swap/bridge quote	Check token pair and amount. Retry the operation.
`ERR_SWAP_FAILED`	2	Token swap failed	Check explorer for details. Verify token pair and liquidity.
`ERR_BRIDGE_FAILED`	2	Cross-chain bridge failed	Check bridge status with `aw bridge status`. Retry if needed.
`ERR_HL_API_FAILED`	2	Hyperliquid API request failed	Retry the operation. Check `aw health` for Hyperliquid status.
`ERR_HL_ORDER_FAILED`	1	Hyperliquid order rejected	Check order parameters (size, leverage, margin).
`ERR_HL_INVALID_ASSET`	1	Invalid perpetual asset	Check available assets with `aw perp assets`.
`ERR_HL_INSUFFICIENT_MARGIN`	1	Insufficient margin for position	Reduce position size or leverage. Check account with `aw perp account`.
`ERR_HL_BUILDER_FEE_FAILED`	2	Failed to apply builder fee	Retry the operation.
`ERR_RED_LINE_BLOCKED`	1	Operation blocked by Security Guard red-line rule	Review the operation. Use `--yes` to confirm after careful review.
`ERR_RATE_LIMITED`	1	Transaction rate limit exceeded	Wait before retrying. Check rate limit status.
`ERR_BLACKLISTED_ADDRESS`	1	Address is blacklisted	Remove from blacklist with `aw security blacklist remove` if legitimate.
`ERR_BASELINE_TAMPERED`	1	Configuration baseline mismatch detected	Investigate configuration changes. Re-init baseline with `aw security baseline init`.
`ERR_PREFLIGHT_FAILED`	1	Security preflight check failed	Review security status with `aw security status`.
`ERR_INTERNAL_ERROR`	2	Unexpected internal error	Retry. If persistent, check `aw health` for diagnostics.

Handling errors in agents

Exit code strategy

import subprocess, json
 
result = subprocess.run(
    ["aw", "send", "--wallet", "bot", "--to", "0x...",
     "--amount", "10", "--token", "USDC", "--json"],
    capture_output=True, text=True
)
 
if result.returncode == 0:
    data = json.loads(result.stdout)["data"]
    print(f"tx_hash: {data['tx_hash']}")
 
elif result.returncode == 3:
    # Auth error — re-unlock and retry
    subprocess.run(["aw", "unlock", "--json"], env={**os.environ, "AW_MASTER_PASSWORD": pw})
    # retry the original command...
 
elif result.returncode == 1:
    error = json.loads(result.stdout)["error"]
    print(f"Error: {error['code']} — {error['recovery_hint']}")
 
elif result.returncode == 2:
    # System error — retry with backoff
    time.sleep(5)
    # retry...

Common patterns

Scenario	Error code	Agent action
Session expired	`ERR_NEED_UNLOCK`	Re-run `aw unlock`, then retry
Over spending limit	`ERR_DAILY_LIMIT_EXCEEDED`	Wait for UTC midnight or reduce amounts
Token not allowed	`ERR_INVALID_PARAMS`	Check policy with `aw policy show`
Network down	`ERR_RPC_UNAVAILABLE`	Retry with exponential backoff
Insufficient funds	`ERR_INSUFFICIENT_FUNDS`	Check balance, request top-up
Duplicate transaction	`ERR_IDEMPOTENCY_CONFLICT`	Use a new idempotency key
Swap failed	`ERR_SWAP_FAILED`	Check token pair, liquidity, retry
Bridge failed	`ERR_BRIDGE_FAILED`	Check `aw bridge status`, retry
Security guard block	`ERR_RED_LINE_BLOCKED`	Review and use `--yes` to confirm
Blacklisted address	`ERR_BLACKLISTED_ADDRESS`	Review blacklist with `aw security blacklist list`
Config tampered	`ERR_BASELINE_TAMPERED`	Investigate, re-init baseline