Execution Errors - Pure API Documentation

Execution errors include error, code (HTTP status), suggestion, and often a stable errorCode. Use errorCode, not the HTTP status alone. On subtotal_mismatch, checkout_expired, or 410, create a new quote. Do not retry the same quoteId with the old expectedTotal. See Execution.

Do not retry

`errorCode` / status	Why
`payment_rollback_failed`, `payment_needs_reconciliation` (422)	Charge may already exist. Contact support.
Failed execute with `unrecoverable: true` (often 422, `errorCode` may be omitted)	Charge or order may already have been attempted. Contact support.
`payment_failed` (402) after a confirm	Verify the method, then a new quote — do not replay the same execute blindly.
`payment_in_progress` (409)	A charge is already running for this quote. Wait; do not start another.

Catalog

Status	`errorCode`	Meaning	What to do
402	`payment_failed`	Payment or payout could not be processed	Check the method, then a new quote
403	—	Organization not allowlisted	Contact support
404	`checkout_not_found`, `cart_not_found`	Quote missing	Check `quoteId` or create a new quote
409	`subtotal_mismatch`	Live buy total went above `expectedTotal`, or live sell payout went below it	New quote, pass the new `total`
409	`listing_validation_failed`, `no_eligible_items`	Items no longer available	New quote with live listings or offers
409	`listing_quantity_mismatch`	Sell qty overlaps your active listings	Listing conflicts, or `adjustListings` / `confirmListingMismatch`
409	`system_check_failed`	Trading halted or eligibility failed	Poll `GET /execution/v2/trading-status`
409	`seller_payment_unavailable`	A listing could not be paid out	New quote
409	`payment_in_progress`	Confirm already has a payment in flight	Wait and retry this quote; do not double-charge
410	`checkout_expired`	Quote window elapsed (sometimes omitted on validation)	New quote
422	`checkout_empty`	Quote has no line items	New quote with at least one item
422	`invalid_quantity`	Quantity is missing or not a positive integer	New quote with quantity ≥ 1
422	`invalid_payment_method`, `payment_method_not_configured`, `stripe_customer_not_configured`, `card_payments_not_allowed`	Payment setup	Use `wire_transfer` or a Stripe `pm_` / `ba_` id; complete Stripe onboarding
422	`optional_fee_mismatch`	Sell optional fee drifted	Refresh quote, pass updated `expectedOptionalFees`
422	`vault_shipping_not_applied`	Vault shipping was requested but did not apply	Check eligibility on optionals
422	`instant_payout_insufficient_credit`	Instant payout credit used up	Drop `instant_payout` or wait for credit
422	`promotion_code_invalid`, `promotion_code_expired`, `promotion_code_not_eligible`, `promotion_code_exhausted`	Promo rejected	Preview again, then execute without the code or with a valid one
422	`payment_rollback_failed`, `payment_needs_reconciliation`	Payment captured but the order did not complete	Contact support — do not retry
500	`system_error`	Unexpected checkout failure	New quote once; if it persists, contact support

Partial fills

Execute can return "status": "partial" with orderId and counterpartyOrderIds for the items that filled. Remaining qty needs a new quote. Buy execute also accepts sweep: true to keep filling leftover size in that confirm.