Reference
Errors and recovery
Common program errors, their causes, and the appropriate recovery action.
Nest rejects an instruction when the supplied state or pricing does not satisfy the program constraints. Most of these errors should update the UI state rather than trigger an automatic retry loop.
| Rejection | Meaning | Safe response |
|---|---|---|
| Protocol or market paused | An administrator or emergency breaker disabled the action | Disable the action and refresh on-chain flags |
| Stale / invalid oracle | Price age, confidence, feed, signature, or instruction proof failed | Fetch a new payload and rebuild the whole transaction |
| Borrow LTV exceeded | Mint or withdrawal would leave debt above the market's borrow limit | Reduce output, add collateral, or repay debt |
| Debt or deposit cap exceeded | A per-vault, market, or protocol cap would be crossed | Display remaining capacity; do not retry unchanged |
| Insufficient collateral / token balance | Wallet or vault cannot fund the requested raw amount | Refresh balances and reduce the amount |
| Bad debt outstanding | Risk-sensitive PSM or staking actions are temporarily unavailable | Disable the action until on-chain bad debt is zero |
| Stake capacity exceeded | The requested deposit would exceed supported staking capacity | Quote a smaller stake from current state |
| Cooldown active | Pending unstake is not claimable yet | Show the chain-derived unlock timestamp |
| Claim window expired | The pending request can no longer receive nUSD | Call cancel_expired_unstake to restore snUSD |
| Pending unstake already exists | The owner PDA already holds one request | Complete or recover it before making another |
| PSM outflow breaker / idle liquidity | Swap-out exceeds the rolling limit or available USDC | Show it as temporarily unavailable; do not bypass it |
Preserve simulation logs
const simulation = await connection.simulateTransaction(transaction);
if (simulation.value.err) {
const diagnostic = {
error: simulation.value.err,
logs: simulation.value.logs ?? [],
unitsConsumed: simulation.value.unitsConsumed,
};
// Show a friendly mapped error to the user. Send this diagnostic only to a
// redacted application logger; never attach wallet secrets or RPC URLs.
throw new Error(JSON.stringify(diagnostic));
}After a blockhash expires, rebuild and re-simulate from fresh account state.
Do not only replace recentBlockhash: deadlines, balances, debt, oracle values,
and output quotes may all have changed.