> For the complete documentation index, see [llms.txt](https://docs.zestprotocol.com/start/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zestprotocol.com/start/stacks-swap-smart-contracts/error-codes.md).

# Error Codes

This page lists the error codes used by the Zest Protocol Stacks Swap contracts. If a swap fails with one of these codes, no funds have moved. The transaction reverted as a whole and the tokens remain in the wallet.

## Error Code Ranges

| Range       | Contract Group   | Description                            |
| ----------- | ---------------- | -------------------------------------- |
| u501-u509   | Adapters         | Per-DEX swap execution errors          |
| u1000-u1016 | Routers (`zr-*`) | Route validation and settlement errors |
| u4003-u4005 | Treasury         | Ownership and administration errors    |

## Router Errors (u1000-u1016)

These come from the router contract that executes the route. Most of them indicate a safety check doing its job, and a fresh quote usually resolves the issue.

| Code  | Name                         | Description                                                                                |
| ----- | ---------------------------- | ------------------------------------------------------------------------------------------ |
| u1000 | ERR\_DEADLINE\_PASSED        | The swap's deadline passed before the transaction confirmed. Request a fresh quote.        |
| u1001 | ERR\_SKIM\_OVER\_MAX         | Protocol fee would exceed the maximum authorized in the signed transaction                 |
| u1002 | ERR\_INSUFFICIENT\_OUTPUT    | Output fell below the minimum received. Price protection triggered; request a fresh quote. |
| u1004 | ERR\_ZERO\_AMOUNT            | Swap amount cannot be zero                                                                 |
| u1005 | ERR\_SKIM\_OVER\_GROSS       | Protocol fee would exceed the swap's gross output                                          |
| u1006 | ERR\_SAME\_TOKEN             | Input and output token are the same                                                        |
| u1007 | ERR\_STX\_BOTH\_SIDES        | STX cannot be both the input and output of a route                                         |
| u1011 | ERR\_STX\_FLOAT              | Safety invariant: the router's STX balance must be unchanged after the swap                |
| u1012 | ERR\_SPLIT\_OUTPUT\_MISMATCH | Safety invariant: combined output of split route legs did not reconcile                    |
| u1013 | ERR\_DELIVERY\_MISMATCH      | Safety invariant: delivered output did not match the measured amount                       |
| u1014 | ERR\_ROUTER\_OUTFLOW         | Safety invariant: unexpected token outflow from the router                                 |
| u1015 | ERR\_INPUT\_DELIVERY         | Safety invariant: swap input was not delivered correctly                                   |
| u1016 | ERR\_INPUT\_OUTFLOW          | Safety invariant: unexpected input-token outflow detected                                  |

## Adapter Errors (u501-u509)

These come from the adapter contract for the DEX the route used. All adapters share the first two codes:

| Code | Name          | Description                                         |
| ---- | ------------- | --------------------------------------------------- |
| u501 | ERR\_ZERO     | Swap amount or pool output was zero                 |
| u502 | ERR\_MIN\_OUT | Pool output fell below the route's required minimum |

Some adapters define additional codes for their platform's safety checks:

**ALEX adapter**

| Code | Name               | Description                                                 |
| ---- | ------------------ | ----------------------------------------------------------- |
| u503 | ERR\_BINDING       | Token binding check failed                                  |
| u504 | ERR\_DELIVERY      | Output delivery check failed                                |
| u505 | ERR\_STX\_STRAND   | Safety invariant: STX left stranded in the adapter          |
| u506 | ERR\_INPUT\_STRAND | Safety invariant: input tokens left stranded in the adapter |

**Bitflow DLMM adapter**

| Code | Name          | Description                                                                |
| ---- | ------------- | -------------------------------------------------------------------------- |
| u504 | ERR\_RESIDUAL | Safety invariant: the adapter must hold no leftover balance after the swap |

**Stacking DAO adapter**

| Code | Name                     | Description                             |
| ---- | ------------------------ | --------------------------------------- |
| u502 | ERR\_RECEIPT / ERR\_POOL | Conversion receipt or pool check failed |
| u503 | ERR\_STX\_FLAG           | Invalid STX flag for this conversion    |
| u504 | ERR\_PAIR                | Unsupported token pair for this adapter |
| u505 | ERR\_DIRECTION           | Unsupported conversion direction        |
| u506 | ERR\_INPUT\_DELTA        | Input amount check failed               |
| u507 | ERR\_OUTPUT\_DELTA       | Output amount check failed              |
| u508 | ERR\_MIN\_OUT            | Output fell below the required minimum  |
| u509 | ERR\_RECEIPT\_USED       | Conversion receipt already used         |

## Treasury Errors (u4003-u4005)

Administrative only. Regular swaps never trigger these.

| Code  | Name                     | Description                             |
| ----- | ------------------------ | --------------------------------------- |
| u4003 | ERR\_NOT\_AUTHORIZED     | Caller is not the treasury owner        |
| u4004 | ERR\_NO\_PENDING\_OWNER  | No pending ownership transfer to accept |
| u4005 | ERR\_NOT\_PENDING\_OWNER | Caller is not the proposed new owner    |

## Debugging Tips

1. **u1000 and u1002** are the most common failures. Both mean a protection fired (stale deadline or price movement). Nothing is lost; request a fresh quote and swap again.
2. **Safety invariant errors** should never occur in normal use. They indicate the contract refusing to settle a swap that does not reconcile exactly. If one occurs repeatedly, contact support with the transaction ID.
3. Any of these errors means the **whole transaction reverted**. Wallet balances remain untouched.