> For the complete documentation index, see [llms.txt](https://docs.keystonefi.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keystonefi.xyz/for-developers/errors.md).

# Error Codes

The `KsusdError` enum lists every program-level error the ksUSD vault can return. Each maps to an Anchor exit code (starting at `0x1770`; the IDL has the exact codes).

> Source: [`programs/keystone-finance/src/errors.rs`](https://github.com/kamwithak/keystone-contracts/blob/main/programs/keystone-finance/src/errors.rs)

***

## General

| Variant         | Meaning                           | Common cause                                                                                                 |
| --------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `Unauthorized`  | Admin / keeper signature required | A non-admin called a privileged instruction, or a non-keeper called strategy when `authorized_keeper` is set |
| `Paused`        | Vault is paused                   | Admin paused; only `withdraw_instant` and `claim_wind_down` still work                                       |
| `MathOverflow`  | Math overflow                     | Bad input or share-price edge case                                                                           |
| `InvalidParams` | Invalid configuration             | Param outside allowed range (e.g. `perf_fee_bps > 5000`) or remaining-accounts split overflow                |

## Deposit / withdraw

| Variant                       | Meaning                                                                                       |
| ----------------------------- | --------------------------------------------------------------------------------------------- |
| `ZeroDeposit`                 | `usdc_amount == 0`                                                                            |
| `DepositCapExceeded`          | New deposit would push `cached_nav_usdc` past `deposit_cap_usdc`                              |
| `InsufficientShares`          | User's ksUSD ATA holds less than requested                                                    |
| `InsufficientLiquidityBuffer` | Vault doesn't have enough idle USDC for instant withdrawal — use `request_withdrawal` instead |
| `SlippageExceeded`            | Realized swap slippage exceeds `max_swap_slippage_bps`                                        |

## Position state

| Variant                  | Meaning                                                                     |
| ------------------------ | --------------------------------------------------------------------------- |
| `PositionAlreadyOpen`    | Calling `open_position` while a position is already open                    |
| `PositionNotOpen`        | Calling `close_position` / `emergency_close` with no active position        |
| `FundingThresholdNotMet` | Keeper attempted to open a mode whose funding-rate threshold wasn't cleared |
| `MinDwellNotElapsed`     | Less than `min_dwell_seconds` since last mode change                        |

## External venues

| Variant             | Meaning                                     |
| ------------------- | ------------------------------------------- |
| `PhoenixCpiFailed`  | The Phoenix CPI returned an error           |
| `KaminoCpiFailed`   | The Kamino KLend CPI returned an error      |
| `JupiterSwapFailed` | The Jupiter V6 route CPI failed             |
| `InvalidMint`       | Account constraint mismatched expected mint |

## Oracle

| Variant                    | Meaning                                              |
| -------------------------- | ---------------------------------------------------- |
| `StaleOracle`              | Pyth price update older than the staleness threshold |
| `OracleConfidenceExceeded` | Pyth confidence interval > 2% of the price           |

## Risk

| Variant                 | Meaning                                                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `EmergencyDrawdown`     | NAV dropped more than `emergency_close_dd_bps` from peak                                                            |
| `LstDepeg`              | jitoSOL price deviated beyond `lst_depeg_bps` — `settle` auto-pauses                                                |
| `DrawdownTriggerLatent` | Drawdown trigger requires N consecutive settles below threshold (set by `consecutive_dd_settles_required`)          |
| `FundingSignalStale`    | Smoothed funding signal older than `funding_max_staleness_seconds`; run `settle` first                              |
| `FundingRateInsane`     | Funding rate sanity check failed (absurd value reported by the perp venue — most likely an oracle / venue incident) |

## Withdrawal queue

| Variant                      | Meaning                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| `WithdrawalAlreadyProcessed` | `process_withdrawal` called on a request that's already settled                       |
| `WithdrawalUserMismatch`     | Recorded `user_usdc_account` doesn't match the passed destination                     |
| `WithdrawalNotNextInQueue`   | Queued requests must be processed strictly in FIFO order — pass the next `request_id` |
| `BelowMinRequestShares`      | `request_withdrawal` shares below `min_request_shares`                                |
| `QueueCapExceeded`           | Queue would exceed `max_pending_queue_usdc`                                           |

## NAV attestation

| Variant               | Meaning                                                            |
| --------------------- | ------------------------------------------------------------------ |
| `NavChangeExceedsCap` | `attest_nav` delta exceeds `max_nav_change_bps_per_hour`           |
| `NavStale`            | NAV stale — `settle` / `attest_nav` required before this operation |

## Lending

| Variant                 | Meaning                                                                 |
| ----------------------- | ----------------------------------------------------------------------- |
| `LendingNotEnabled`     | `lend_idle_usdc` / `lend_reserve` called without prior `enable_lending` |
| `LendingBreachesBuffer` | Lending more would drop idle USDC below `liquidity_buffer_target`       |

## Wind-down / admin transfer

| Variant           | Meaning                                                             |
| ----------------- | ------------------------------------------------------------------- |
| `WindDownActive`  | Vault is in wind-down — new deposits / positions / un-pause blocked |
| `NoPendingAdmin`  | `accept_admin` called when no pending admin is set                  |
| `NotPendingAdmin` | `accept_admin` signer doesn't match `pending_admin`                 |

## Bootstrap

| Variant                 | Meaning                                                                            |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `BootstrapResidualUsdc` | Vault USDC ATA must be empty before the first deposit (prevents dilution griefing) |

***

## Reading errors from a client

```ts
try {
  await program.methods.withdrawInstant(new BN(amount)).accountsStrict({...}).rpc();
} catch (e: any) {
  // AnchorError exposes .error.errorCode.code (string) and .error.errorMessage
  if (e.error?.errorCode?.code === "InsufficientLiquidityBuffer") {
    // fall back to request_withdrawal
  }
  throw e;
}
```

In raw transaction logs the error appears as e.g. `AnchorError caused by account: ... InsufficientLiquidityBuffer.` followed by the exit code.

***

## Related

* [Instructions](/for-developers/instructions.md) · [Account structure](/for-developers/accounts.md) · [Events](/for-developers/events.md)