Stacks Swap
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
- 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.
- 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.
- Any of these errors means the whole transaction reverted. Wallet balances remain untouched.
Last updated on