error_code you can branch on. Match on the code, not the message — messages may be reworded.
Status codes
Error codes
amount_below_minimum
amount_below_minimum
The order is too small for the deposit rail on that chain, where we sponsor a fixed cost per payment.Do: offer the connect rail, which has no minimum, or suggest a cheaper chain. Limits.
merchant_not_attested
merchant_not_attested
No payout address is attested on-chain for this merchant, so a payment would have nowhere safe to go.Do: set your payout address in Settings → Payout. If a customer hit this, the checkout will have shown “merchant hasn’t completed setup” rather than taking money.
pool_not_deployed
pool_not_deployed
The connect rail needs a deployed pool on that chain.
deposit() is a contract call and reverts against an address with no code.Do: deploy the pool, or use the deposit rail, which works pre-deploy.chain_not_activated
chain_not_activated
That chain isn’t enabled on your account.Do: enable it in Tokens, or quote a chain you have enabled.
token_not_enabled
token_not_enabled
That (token, chain) pair is disabled. Enforced server-side, so hiding it in your UI isn’t sufficient on its own.Do: enable the pair, or quote a different one.
quote_expired
quote_expired
The price window lapsed before payment creation.Do: create a fresh quote. Note this concerns quoting — a customer who pays a previously issued address late is still credited. Finality.
payment_blocked
payment_blocked
A compliance check refused the payment. Deliberately non-specific, to avoid coaching evasion.Do: nothing automated. Only fires if you’ve enabled payer screening. Sanctions.
rate_limited
rate_limited
Too many requests.Do: back off for the duration in
Retry-After. The embedded checkout handles this automatically with a countdown.pool_mismatch
pool_mismatch
Not an API error — a checkout state. The on-chain verification failed, so signing is blocked and the payment address is hidden.Do: treat as serious. Check your payout settings and the
settlementAnchor in your embed. This is the protection doing its job. Verification.Handling them
Still stuck
Check the dashboard
Readiness state, recent payments, webhook deliveries.
Verify on-chain
Confirm contracts and addresses independently.