This section outlines how Helios reports errors, enforces limits, and should be used in production systems.

Error Handling

Helios errors are explicit, structured, and designed to be handled programmatically.

All errors follow a consistent format.

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

Always rely on the code, not the message, for logic.

Common Error Codes

INVALID_REQUEST
Request parameters are missing, malformed, or invalid.

AUTHENTICATION_FAILED
API key, signature, or permissions are incorrect.

INSUFFICIENT_LIQUIDITY
Available liquidity cannot satisfy the execution under current constraints.

RISK_THRESHOLD_EXCEEDED
Execution blocked due to configured risk limits.

EXECUTION_FAILED
Transaction was submitted but reverted or failed on-chain.

RATE_LIMIT_EXCEEDED
Request frequency exceeded allowed limits.

Handling Errors Safely

Errors should not be retried blindly.

try {
  await helios.execute(params);
} catch (err) {
  if (err.code === "INSUFFICIENT_LIQUIDITY") {
    await helios.simulate(params);
  }
}

Always re-simulate before retrying failed executions.

Rate Limits

Helios enforces rate limits per API key.

Limits vary by:

• Environment

• Endpoint type

• Account tier

When exceeded, the API returns:

429 Too Many Requests

Rate limit metadata is included in response headers.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

Clients should implement backoff and retry strategies.

Execution Limits

Helios enforces execution-level constraints to protect system stability.

Limits may apply to:

• Maximum transaction size

• Route complexity

• Cross-chain depth

• Simulation frequency

Requests exceeding these limits return validation errors before execution.

Idempotency & Retries

Helios execution requests are not idempotent by default.

Retries should:

• Be preceded by a fresh simulation

• Use updated market and risk data

• Avoid reusing stale execution parameters

Webhook events may be delivered more than once and must be handled idempotently.