---
title: Errors
description: Decode SV3 custom errors from simulation failures and reverted receipts.
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

SDK failures are `Sv3Error` subclasses with a stable `code`. On-chain reverts are decoded against `protocolErrorsAbi`. You should not parse provider strings.

`parseProtocolError` walks nested viem `cause` / `data`, so a `simulateContract` failure still yields `SlippageExceeded` instead of a hex blob.

## Import

```ts
import {
  parseProtocolError,
  toProtocolRevertError,
  ProtocolRevertError,
} from "@repo/contract-client";
```

On a client: `sv3.errors.parse` and `sv3.errors.toError`.

## Usage

```ts
try {
  await sv3.transactions.executePrepared(prepared);
} catch (error) {
  const revert = toProtocolRevertError(error);
  revert.errorName;
  // 'SlippageExceeded' | 'BelowMinimum' | 'ProtocolPaused' | …
  revert.errorArgs;
}
```

`parseProtocolError` accepts revert hex, a nested viem error, or any object with `data` / `cause`. It classifies:

| `kind`     | Meaning                         |
| ---------- | ------------------------------- |
| `protocol` | Named custom error from the ABI |
| `empty`    | `0x` revert data                |
| `panic`    | Solidity panic (`0x4e487b71…`)  |
| `unknown`  | Anything else                   |

Empty data and panics are fallbacks, not the UX for ordinary invalid inputs.

Simulation failures are `SimulationFailedError` with a `ProtocolRevertError` as `cause`. Mined reverts are `TransactionRevertedError` with the same decode after [wait](/developers/wait).

## Common protocol names

`BelowMinimum`, `SlippageExceeded`, `MaxInputExceeded`, `ProtocolPaused`, `MarketPaused`, `ZeroAmount`, `BorrowCapacityExceeded`, `InsufficientFreeCollateral`, `InsufficientBacking`, `CanaryCapExceeded`, `Expired`.

Local math throws the same names (`BelowMinimum`, `BorrowCapacityExceeded`, …) so a slider failure matches simulate.

## Client errors

| Error                           | When                                     |
| ------------------------------- | ---------------------------------------- |
| `UnsupportedChainError`         | `chainId` not `8453` / `31337`           |
| `UnsupportedCurveRevisionError` | Snapshot math is not in `SUPPORTED_MATH` |
| `WalletClientRequiredError`     | Write without a wallet                   |
| `AccountMismatchError`          | Prepared account ≠ wallet                |
| `StaleStateError`               | Market nonce moved before send           |
| `InvalidDeadlineError`          | Deadline config out of range             |
| `InvalidAmountError`            | Signed or zero inputs in unit math       |
| `SimulationFailedError`         | Simulate reverted                        |
| `TransactionRejectedError`      | Wallet rejected                          |
| `TransactionRevertedError`      | Mined revert                             |

## Tips

- Compare `errorName`, not the message string. Messages are for logs.
- `encodeProtocolError({ errorName, args })` is exported for tests.