> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rhaios.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common Rhaios API errors, causes, and concrete fixes.

# 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.

<Note>
  Preflight simulation failures always block execution. This is intentional — a reverted simulation means the transaction would fail on-chain.
</Note>

## Test RPC and testing endpoint errors

See [Test RPCs](/concepts/test-rpc) for background on managed chain forks.

### `Anvil forks not configured`

Cause: Setup relay requires a managed [test RPC](/concepts/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`](/tools/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.