Stacks Pools

Error Codes

This page lists the error codes used by the Zest Protocol concentrated liquidity contracts. A call that fails with one of these codes reverts as a whole, and no tokens move.

Error Code Ranges

Range	Contract	Description
u1-u4	`clmm-lp-token-v1`	Share transfer errors
u1000-u1008	`clmm-pool-v1`	Authorization and pool state
u1000-u1002	`executor-dao`	Proposal execution
u2000-u2013	`clmm-pool-v1`	Inputs, positions, swaps and limits
u3002-u3007	`clmm-pool-v1`	Arithmetic bounds and transfer checks
u4000-u4005	`operators`	Multisig approvals
u5001-u5004	`clmm-router-v1`	Route results

Several contracts use u1000 for “not authorized”; the contract that returned the error tells them apart.

Pool Errors (u1000-u1008)

Code	Name	Description
u1000	ERR-NOT-AUTHORIZED	Caller is not governance, or a withdrawal was not called directly by the owner
u1001	ERR-POOL-PAUSED	The pool is paused. Swaps and deposits are stopped; withdrawals still work.
u1002	ERR-POOL-SUNSET	The pool is sunset. Deposits are stopped; swaps and withdrawals still work.
u1003	ERR-POOL-NOT-FOUND	No pool with this id
u1004	ERR-INVALID-PAIR	A pool’s two tokens must differ
u1005	ERR-TOKEN-LISTED	A token’s native STX flag cannot change once a pool uses it
u1006	ERR-NOT-DEPOSITOR	Only a private pool’s depositor can add liquidity
u1007	ERR-PRIVATE-POOL	Private pools take no partner discounts
u1008	ERR-PUBLIC-POOL	A public pool has no depositor to move

Input, Position and Swap Errors (u2000-u2013)

Code	Name	Description
u2000	ERR-POOL-ALREADY-EXISTS	A public pool already exists for this pair and bin step, in either token order
u2001	ERR-INVALID-PRICE	The bin price after a deposit falls outside the deposit’s price bounds. Re-quote the deposit.
u2002	ERR-INVALID-TOKEN-TRAIT	The token contracts passed are not the pool’s token X and token Y
u2003	ERR-INVALID-BIN-STEP	Bin step must be `u100`, `u500`, `u1000` or `u2000`
u2004	ERR-PERCENT-GREATER-THAN-ONE	A percentage, LP fee share or discount is above 100%
u2005	ERR-ZERO-PERCENT	The withdrawal would burn zero shares
u2006	ERR-INVALID-AMOUNT	A deposit must add some X or some Y
u2007	ERR-POSITION-NOT-FOUND	The bin has never held liquidity
u2008	ERR-PERCENT-GREATER-THAN-OR-EQUALS-ONE	A fee rate must be below 100%
u2009	ERR-SLIPPAGE	Output or shares fell below the minimum in the transaction. Request a fresh quote.
u2010	ERR-NOT-FILLED	A route that does not allow partial fills could not spend the whole input
u2011	ERR-INVALID-ROUTE	Route ticks are not strictly ascending (X to Y) or strictly descending (Y to X)
u2012	ERR-FEE-TOO-HIGH	A pool’s fee rate cannot exceed 10%
u2013	ERR-EXPIRED	The deadline passed before the transaction was mined. Request a fresh quote.

Arithmetic and Transfer Errors (u3002-u3007)

Code	Name	Description
u3002	ERR-INVALID-LP-STATE	The deposit would mint zero shares
u3003	ERR-MAX-POOLS-ALLOWED	The pool contract has reached its maximum number of pools
u3004	ERR-TICK-OUT-OF-RANGE	The tick is outside the bin step’s usable range
u3005	ERR-AMOUNT-TOO-LARGE	An amount, or a bin’s reserve after the trade, exceeds the bin’s size bound (2¹¹⁸ base units, scaled)
u3006	ERR-MATH-OVERFLOW	An intermediate result does not fit
u3007	ERR-TRANSFER-MISMATCH	Safety invariant: a transfer moved a different amount than requested

Router Errors (u5001-u5004)

The router maps the pool’s route errors onto its own codes. Other pool errors pass through unchanged.

Code	Name	Pool code	Description
u5001	ERR-INSUFFICIENT-LIQUIDITY	u2010	The bins could not take the whole input (fill-or-kill or a full route)
u5002	ERR-SLIPPAGE	u2009	Output fell below the minimum. Request a fresh quote.
u5003	ERR-INVALID-ROUTE	u2011	Tick order is wrong, or the token path and hops do not match
u5004	ERR-EXPIRED	u2013	The deadline passed. Request a fresh quote.

LP Token Errors (u1-u4, u1000)

Code	Name	Description
u1	ERR-INSUFFICIENT-BALANCE	The sender does not hold enough shares of this bin
u2	ERR-SAME-PRINCIPAL	Sender and recipient are the same
u3	ERR-ZERO-AMOUNT	Transfer amount cannot be zero
u4	ERR-INVALID-SENDER	The sender must be the immediate caller
u1000	ERR-NOT-AUTHORIZED	Transfers are disabled, or only the pool may mint and burn

Governance Errors

executor-dao

Code	Name	Description
u1000	ERR-UNAUTHORISED	Caller is not the DAO or an enabled extension
u1001	ERR-ALREADY-EXECUTED	The proposal has already been executed
u1002	ERR-INVALID-EXTENSION	An extension callback came from a contract that is not an enabled extension

operators

Code	Name	Description
u4000	ERR-NOT-AUTHORIZED	Caller is not the DAO or an enabled extension
u4001	ERR-NOT-OPERATOR	Caller is not an operator
u4002	ERR-ALREADY-APPROVED	This operator has already approved the proposal
u4003	ERR-ALREADY-EXECUTED	The proposal has already been executed
u4004	ERR-EXPIRED	The approval window for the proposal has closed
u4005	ERR-INVALID-THRESHOLD	The threshold must be at least 1 and at most the number of operators

Debugging Tips

Deadline and slippage errors (u2009, u2013, u5002, u5004) are the most common failures. All four mean a protection fired. Nothing is lost; request a fresh quote and try again.
u2001 on a deposit means the bin traded before the deposit confirmed. Re-quote and set price bounds from the new state.
u1000 on a withdrawal means the owner did not call the pool directly. Call reduce-position or reduce-positions from the wallet that holds the shares, or from inside the holding contract’s as-contract?.
u3007 should never occur with a supported token. The code means the pool refused a transfer that did not reconcile exactly. If one occurs, contact support with the transaction ID.