Error Codes

Every error the contract can return, with the likely cause and the fix.

When a contract call fails, the transaction reverts with a numeric error code like u1001. The frontend maps these to friendly messages, but when you're debugging directly you'll want the full catalog.

Where you'll see these

Error codes appear in wallet rejection dialogs, in transaction failure pages on the Hiro Explorer, and in the result field of failed chainhook events.

Authorization errors

Code	Type	Description
`u1000`	`ERR_UNAUTHORIZED`	The caller is not allowed to perform this action. Usually means you're trying to act on someone else's invoice/subscription/merchant record.
`u1001`	`ERR_NOT_OWNER`	Only the contract deployer can call this function (e.g., updating the fee rate or pausing the contract).
`u1002`	`ERR_CONTRACT_PAUSED`	The contract has been paused for maintenance. Wait for an unpause before retrying.

Merchant errors

Code	Type	Description
`u2000`	`ERR_MERCHANT_NOT_FOUND`	No merchant is registered for the given principal. Register first with register-merchant.
`u2001`	`ERR_MERCHANT_ALREADY_REGISTERED`	This wallet is already registered as a merchant.
`u2002`	`ERR_MERCHANT_INACTIVE`	The merchant has been deactivated and cannot accept new payments.
`u2003`	`ERR_MERCHANT_SUSPENDED`	The merchant has been administratively suspended.

Invoice errors

Code	Type	Description
`u3000`	`ERR_INVOICE_NOT_FOUND`	No invoice with this ID exists.
`u3001`	`ERR_INVOICE_EXPIRED`	The invoice's expires-at block has passed. Create a new invoice.
`u3002`	`ERR_INVOICE_CANCELLED`	The merchant cancelled this invoice.
`u3003`	`ERR_INVOICE_ALREADY_PAID`	Invoice is fully paid. For partial invoices, this means total received = amount.
`u3004`	`ERR_AMOUNT_TOO_LOW`	Payment amount is less than the minimum, or you're trying to pay less than full on an invoice that doesn't allow partial payments.
`u3005`	`ERR_AMOUNT_TOO_HIGH`	Payment amount exceeds the invoice amount and allow-overpay is false.
`u3006`	`ERR_INVOICE_NOT_PAYABLE`	Invoice is in a status (cancelled, expired, refunded) that doesn't accept payments.
`u3007`	`ERR_INVOICE_LOCKED`	Invoice has received at least one payment and can no longer be updated — only refunded.

Subscription errors

Code	Type	Description
`u4000`	`ERR_SUBSCRIPTION_NOT_FOUND`	No subscription with this ID exists.
`u4001`	`ERR_SUBSCRIPTION_CANCELLED`	Subscription is cancelled. Create a new one to resubscribe.
`u4002`	`ERR_NOT_DUE_YET`	Payment is attempted before next-payment-at. Wait for the interval to elapse.
`u4003`	`ERR_SUBSCRIPTION_PAUSED`	Subscription is paused. Resume it before paying.
`u4004`	`ERR_ALREADY_PAUSED`	You tried to pause a subscription that's already paused.
`u4005`	`ERR_NOT_PAUSED`	You tried to resume a subscription that isn't paused.

Refund errors

Code	Type	Description
`u5000`	`ERR_REFUND_WINDOW_EXPIRED`	The invoice is too old to refund. Refund window is measured from first-payment-at.
`u5001`	`ERR_REFUND_EXCEEDS_PAID`	You tried to refund more than the total amount paid on this invoice.
`u5002`	`ERR_INVOICE_NOT_PAID`	You can only refund invoices that have received at least one payment.
`u5003`	`ERR_INVALID_REFUND_AMOUNT`	Refund amount must be greater than zero.

Token / transfer errors

Code	Type	Description
`u6000`	`ERR_INVALID_TOKEN_TYPE`	Unknown token type. Must be u0 (sBTC) or u1 (STX).
`u6001`	`ERR_TRANSFER_FAILED`	The underlying token transfer failed — usually means sender has insufficient balance.
`u6002`	`ERR_INSUFFICIENT_BALANCE`	Sender wallet doesn't have enough of the token to cover the payment or refund.

What to show users

The frontend's CONTRACT_ERRORS map translates these codes into human-friendly messages. When you integrate, check that map first — if you see an error like u5000 in production, you can match it to the appropriate user message ("This invoice is too old to refund") rather than showing the raw code.