Errors & recovery
Help the buyer recover without creating a duplicate purchase.
Check the error string as well as the HTTP status. Give the buyer a useful message and retain the checkout ID or signature for support. Do not display raw diagnostic messages.
| Code or condition | What to do |
|---|---|
PLATFORM_KEY_INVALID | Check the server credential and selected environment |
VALIDATION_ERROR | Correct the fields identified by details, when present |
RAFFLE_NOT_FOUND | Refresh the raffle list; the raffle is unavailable to your platform |
RAFFLE_CLOSED, RAFFLE_NOT_LIVE | Stop new purchases and refresh raffle details |
RAFFLE_MAX_ENTRIES_EXCEEDED | Explain that the selected quantity is unavailable; no partial fill |
RAFFLE_WALLET_LIMIT_EXCEEDED | Explain the purchase limit and refresh the buyer's position |
RAFFLE_PURCHASE_IN_PROGRESS | Resume the buyer's existing checkout |
IDEMPOTENCY_KEY_REUSED | Recover the original purchase; do not reuse its key with different details |
PAYMENT_NOT_FOUND | Check the saved operation ID, environment and platform |
PAYMENT_RETRY_NOT_ALLOWED | Keep tracking the existing payment; do not replace its signature |
PAYMENTS_UNAVAILABLE | Temporarily disable new checkout attempts and retry later |
| Timeout or 5xx | Retry a purchase request with the same identity; query status before any new payment |
Wallet payment problems
TX_MEMO_MISMATCH, TX_AMOUNT_MISMATCH, TX_WRONG_MINT, and TX_USED_UNCHECKED_TRANSFER indicate a problem with the submitted transaction. Check the payment format. If funds moved, inspect the checkout or refund status before allowing another payment.
For payment-first integrations, TX_NOT_FOUND can mean the transaction is not yet visible at finalized commitment. Retry the same signature. PAYMENT_REFUND_IN_FLIGHT means wait; PAYMENT_REFUNDED with refund_status: "paid" confirms completion. PAYMENT_REFUND_FAILED needs Verity support.
Redemption problems
| Code | What to do |
|---|---|
WALLET_SESSION_EXPIRED, WALLET_SIGNATURE_INVALID | Sign in with the wallet again and resume the same order |
DHL_VALIDATION_FAILED | Ask the buyer to review the address |
DHL_ROUTE_UNAVAILABLE, SHIPPING_DESTINATION_UNSUPPORTED | Explain that shipping is unavailable to that destination |
RATE_CHANGED | Fetch a new quote and request confirmation |
REDEMPTION_IN_PROGRESS, STOCK_REDEMPTION_IN_PROGRESS | Open or resume the existing redemption |
ITEM_NOT_READY, ITEM_AWARD_PROCESSING, ITEM_OPERATION_IN_PROGRESS | Refresh the prize state later; do not show a mint action |
RATE_LIMITED | Wait for the Retry-After interval |
DHL_UNAVAILABLE | Let the buyer retry later without creating another order |
The API may add error codes. Provide a fallback that preserves the purchase or redemption identity and links the buyer to support.