Skip to main content
Errors return a JSON body with a stable error_code you can branch on. Match on the code, not the message — messages may be reworded.

Status codes

Error codes

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.
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.
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.
That chain isn’t enabled on your account.Do: enable it in Tokens, or quote a chain you have 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.
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.
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.
Too many requests.Do: back off for the duration in Retry-After. The embedded checkout handles this automatically with a countdown.
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

Distinguish customer-recoverable errors — try another chain, wait a moment — from merchant configuration errors, which the customer can do nothing about. The second kind should page you, not confuse them.

Still stuck

Check the dashboard

Readiness state, recent payments, webhook deliveries.

Verify on-chain

Confirm contracts and addresses independently.