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.