Common errors and Troubleshooting

All Helios API calls return structured, machine-readable responses.
Responses are designed to be deterministic and easy to reason about in production systems.

Execution Response Shape

A successful execution returns the following core fields:

{
  "id": "hx_88421a",
  "status": "executed",
  "fromChain": "ethereum",
  "toChain": "arbitrum",
  "asset": "USDC",
  "amount": "4500",
  "txHash": "0xf3a1...c92b",
  "gasUsed": 183210,
  "route": {
    "protocols": ["UniswapV3", "BridgeX"],
    "slippage": 0.42
  },
  "timestamp": 1737048129
}

Execution Status Values

The status field reflects the real execution state.

simulated — Route and costs calculated, no transaction sent
pending — Transaction submitted, awaiting confirmation
executed — Transaction finalized on-chain
failed — Execution failed and was not finalized

Helios does not mark an execution as successful unless it is confirmed on-chain.

Partial Execution Awareness

In multi-step or cross-chain executions, Helios reports progress per step internally.
The final status reflects the aggregate outcome of the execution flow.

Common Errors

Errors are returned with explicit types and messages.
They are designed to be actionable rather than ambiguous.

Example Error Response

{
  "error": {
    "code": "INSUFFICIENT_LIQUIDITY",
    "message": "Not enough liquidity available for the requested amount",
    "details": {
      "asset": "USDC",
      "requested": "4500"
    }
  }
}

Frequently Encountered Errors

INVALID_REQUEST
Returned when required parameters are missing or malformed.

INSUFFICIENT_LIQUIDITY
Available liquidity cannot satisfy the execution under current constraints.

RISK_THRESHOLD_EXCEEDED
Execution was blocked due to risk signals exceeding the configured level.

UNSUPPORTED_CHAIN
One or more chains in the request are not supported in the selected environment.

EXECUTION_FAILED
The transaction was submitted but reverted or failed to finalize on-chain.

Troubleshooting

When an execution fails, follow this sequence.

Step 1: Run a Simulation

Always simulate first to validate routing and cost assumptions.

await helios.simulate({ ...params });

Simulation failures usually indicate configuration or liquidity issues.

Step 2: Inspect Risk Signals

If execution fails due to risk constraints, review or adjust the risk level.

options: {
  riskLevel: "conservative" | "balanced" | "aggressive"
}

Lower risk levels may block volatile or shallow routes.

Step 3: Check Slippage and Fees

Overly strict slippage tolerances can cause failed executions during market movement.

options: {
  slippage: 0.5
}

Increase cautiously if execution reliability is prioritized over price precision.

Step 4: Verify Signing and Gas

Ensure:

The transaction was signed correctly
Sufficient gas and native token balance are available
Network congestion is accounted for

Helios estimates gas but does not fund or sign transactions.

Quickstart

Common errors and Troubleshooting