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

# Errors

> Typed exception taxonomy: catch precisely, retry safely.

Every failure raises a typed exception from `avantis_trader_sdk.errors`, all descending from `AvantisError`.

```python theme={null}
from avantis_trader_sdk.errors import ValidationError, RelayTimeoutError

try:
    await client.trade.market_open("ETH/USD", "long", collateral=100, leverage=10)
except ValidationError as e:
    print("rejected:", e.code, e.details)     # fix the order, don't retry as-is
except RelayTimeoutError:
    ...                                        # poll positions before resubmitting
```

## Hierarchy

| Exception                  | Raised when                                                                                                                                                                                                                                                                                                 | Retry?                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `ConfigError`              | Missing/invalid configuration (no key, unknown option)                                                                                                                                                                                                                                                      | No, fix config                                             |
| `ApiError`                 | An Avantis API returned an error envelope (`.code`, `.status`, `.details`, `.url`)                                                                                                                                                                                                                          | Depends on subclass                                        |
|   `ValidationError`        | 400: pre-trade validation or bad request shape                                                                                                                                                                                                                                                              | No, fix the order                                          |
|   `SimulationFailedError`  | Relay simulation reverted (`.details` may carry the decoded revert)                                                                                                                                                                                                                                         | Usually stale state; re-fetch positions first              |
|   `RateLimitedError`       | 429                                                                                                                                                                                                                                                                                                         | Yes, with backoff                                          |
|   `GeoRestrictedError`     | 451                                                                                                                                                                                                                                                                                                         | No                                                         |
|   `UpstreamError`          | 502: upstream RPC/API failure on the server side                                                                                                                                                                                                                                                            | Yes, with backoff                                          |
| `SigningError`             | Local signing failure                                                                                                                                                                                                                                                                                       | No                                                         |
|   `DigestMismatchError`    | Local EIP-712 digest ≠ API digest                                                                                                                                                                                                                                                                           | **Never** (see below)                                      |
| `RelayError`               | Relayer rejected/failed the request (`.request_id`), or the batched-market service declined the fill (`MarketOrderCanceled`, e.g. slippage) or failed it (terminal `Error`; `.code` carries the machine-readable reason — a contract error name like `WrongSl` or a service code like `ATTEMPTS_EXHAUSTED`) | Branch on `.code`; treat unknown codes as generic failures |
|   `RelayTimeoutError`      | Not settled within `relay_poll_timeout_s`                                                                                                                                                                                                                                                                   | Check positions first; it may still land                   |
| `RpcError`                 | JSON-RPC failure in direct mode (`.code`, `.data`)                                                                                                                                                                                                                                                          | Depends on code                                            |
| `TransactionRevertedError` | Transaction mined but reverted (`.tx_hash`)                                                                                                                                                                                                                                                                 | Inspect on-chain                                           |
| `DelegationError`          | Delegate missing, disabled, or expired                                                                                                                                                                                                                                                                      | Re-register the delegate                                   |

<Warning>
  `DigestMismatchError` means the SDK's local encoding disagrees with the API, either encoding drift or a tampered response. Nothing was signed or submitted. Do not work around it; upgrade the SDK or report the issue.
</Warning>

<Note>
  On `RelayTimeoutError`, the order may still settle after the polling window. Check `client.account.positions()` before resubmitting, or you may end up with a double fill.
</Note>