Skip to main content

​
Troubleshooting

Use this page when your API call fails or returns unexpected output.

​
Endpoint and transport issues

​
HTTP 404 or wrong URL

Cause: Request URL does not match a valid API endpoint. Fix:
  • Verify you are using the correct base URL: https://api.staging.rhaios.com
  • Check that the endpoint path is correct (e.g., POST /v1/yield/discover, not /mcp).
  • Check GET https://api.staging.rhaios.com/health to verify the API is reachable.

​
POST /v1/yield/prepare errors

​
Payment required

Cause: x402 is enabled on the server and payment was not attached or not verified. Fix:
  • Ensure your client supports x402 and can attach the X-PAYMENT header after receiving HTTP 402.
  • If you expected free mode, switch to the intended environment or contact Rhaios support.

​
No suitable vaults found

Cause: No active vault matched your filters (asset, chain, risk). Fix:
  • Use asset: "USDC" and chain: "base" first.
  • Remove strict filters (riskTolerance, aggressive strategy overrides).
  • Retry with a larger universe (different chain or strategy).

​
POST /v1/yield/execute errors

​
Transaction validation failed

Cause: Signed tx did not match policy (wrong type, wrong chain, wrong target). Fix:
  • Ensure tx is Type 2 or Type 4.
  • Ensure to is EntryPoint (0x0000000071727De22E5E9d8BAf0edAc6f37da032).
  • Ensure chain is Base (8453) or Ethereum (1) for pre-prod/prod profiles.

​
Transaction submission failed with aaCode

POST /v1/yield/execute surfaces common account-abstraction errors:
  • AA50: postOp reverted (often paymaster/postOp issue)
  • AA24: signature validation failure
  • AA21: account not funded / prefund issue
Fix:
  • Rebuild calldata via POST /v1/yield/prepare, then re-sign (for AA24).
  • Check gas sponsorship/funding path (for AA21/AA50).
  • Retry once if RPC/bundler transient failure is suspected.

​
Preflight simulation errors

​
Preflight simulation failed

Cause: The server runs a preflight simulation on an ephemeral fork before submitting your transaction. If simulation reverts, execution is blocked. Fix:
  • Check that your wallet has sufficient token balance and approvals for the operation.
  • Rebuild calldata via POST /v1/yield/prepare (on-chain state may have changed since preparation).
  • If the error includes a revert reason (e.g., INSUFFICIENT_BALANCE), address the underlying cause.
Preflight simulation failures always block execution. This is intentional — a reverted simulation means the transaction would fail on-chain.

​
Test RPC and testing endpoint errors

See Test RPCs for background on managed chain forks.

​
Anvil forks not configured

Cause: Setup relay requires a managed test RPC, which is not configured on this deployment. Fix:
  • This is an operator-side configuration issue. Contact Rhaios support.
  • For local development, set ANVIL_FORKS_URL and ANVIL_FORKS_ADMIN_TOKEN in your environment.

​
Fork is not running or funding errors

Cause: The test RPC for the target chain is unavailable or was evicted. Fix:
  • Call GET /v1/testing/fork-status to check test RPC health before funding.
  • Retry the operation — the server will recreate the fork automatically.
  • If persistent, contact Rhaios support.

​
RPC and network issues

Symptoms:
  • Timeout errors
  • fetch failed
  • Receipt not found
Fix:
  • Check https://api.staging.rhaios.com/health first.
  • Retry with backoff (2-3 attempts).
  • Verify upstream status for your RPC provider.
  • If persistent, share timestamps and failing endpoint calls with Rhaios support.

​
Data freshness issues

If strategy quality looks stale:
  • Retry after a short delay (snapshots update over time).
  • Compare updatedAt or timestamp fields in responses across retries.
  • If values remain stale for an extended window, contact Rhaios support.