- Detecting which program the error came from
- Mapping it to a user-facing message
- Deciding between retry, prompt, or give-up
Shape of an Anchor error in logs
Error Number and the emitting program ID to route
errors to the right enum.
Parsing helper
frontend/app/lib/errors.ts for the full mapping the reference UI uses.
Error categories by program
kimia-perp (6000..6199)
| Bucket | Codes | Typical recovery |
|---|---|---|
| Oracle | 6000-6002 | Retry (auto-reposts Hermes update) |
| Market lifecycle | 6010-6012 | Wait for admin / switch market |
| Margin | 6020-6022 | Deposit more collateral, reduce size |
| Position | 6030-6033 | Fix size / direction |
| Funding | 6040-6041 | Wait for the funding period to elapse |
| Liquidation | 6050-6051 | Account not liquidatable (healthy) |
| Deposit/withdraw | 6060-6061 | Amount > 0; enough balance |
| Math | 6070 | Reduce size; hits u128 intermediates |
| Auth | 6080-6081 | Use authority wallet; delegate can’t withdraw |
| Slippage | 6090 | Raise max_slippage_bps |
| Insurance | 6100 | Bad debt; market paused until admin |
| Orderbook | 6110-6117 | Book full, order not found, crossing post-only, market-order slippage |
| Spot pool | 6130-6133 | Pool paused, insufficient liquidity, swap slippage, zero amount |
delta-vault
| Error | Recovery |
|---|---|
VaultNotActive | Wait for admin resume |
VaultNotPaused | Admin-only paths require paused state |
PerpsUserAccountNotInit | Call init_perps_user_account once |
NavCorrupted | Admin admin_resync_nav; shouldn’t happen in normal ops |
DeltaExceedsThreshold | Spot/perp legs have diverged more than the rebalance cap |
VaultNotMigrated | Admin must run admin_setup_spot_leg before first deposit |
split-engine
| Error | Recovery |
|---|---|
NotMatured | Wait until maturity timestamp |
AlreadyMatured | Use redeem_pt instead of deposit |
NoYieldToClaim | Nothing to claim yet; call update_rewards first |
SupplyInvariantViolated | Protocol bug, do not ignore; report it |
ZeroDeposit | Deposit amount must be greater than zero |
yield-amm
| Error | Recovery |
|---|---|
SwapDisabledNearMaturity | Too close to maturity; just redeem_pt |
SlippageExceeded | Raise min_amount_out tolerance |
InsufficientLiquidity | Larger size than pool supports |
EmptyPool | Pool hasn’t been seeded yet |
InvariantViolated | Post-swap invariant check failed — retry with smaller size |
intent-router
| Error | Recovery |
|---|---|
InvalidSessionState | Step must follow Created → Step1 → Step2 → Step3 |
TargetRateNotAchievable | Lower target, or wait for AMM to recover |
TargetRateNotAchieved | Achieved rate was below target at step 3; session stays at Step2Complete |
PtBalanceMismatch | Step 2 can’t account for expected PT |
NegativeDiscount | PT redeemed for more than face value |
InvalidDuration | Session duration must be greater than zero |
Retry policy
Auto-retryable errors:StaleOracle, re-fetch Hermes, rebuild tx, retry.- RPC transient errors (connection, blockhash not found), exponential backoff.
SlippageExceeded, ask the user to raise slippage tolerance.InsufficientFreeCollateral, prompt a deposit or cancel-orders flow.
MarketNotActive,VaultNotActive, nothing the user can do until admin.- Math errors (
MathOverflow), your input was too large; don’t retry.
Logging raw errors
For unknown or unmapped errors, log:- Transaction signature
- Program logs (
tx.meta.logMessages) - Which instruction in the tx failed (Anchor logs
Instruction: X)

