Error Codes & Failure Modes

AAR introduces additional standardized error codes for quote and route issues. When a client retries after paying fails, the merchant may return 402 again with one of these in X-402-AAR-ERROR (base64url compact JSON).

Code	Name	Description	Client Action
Q1	QUOTE_EXPIRED	deadlineTs passed.	Request a fresh quote.
Q2	QUOTE_MISMATCH	quoteId unknown or not bound to offerId.	Refresh route with current offer.
S1	SETTLEMENT_UNDERPAID	amountOut below minOut or merchant-required amount.	Increase amountInMax / new quote.
S2	WRONG_ASSET_OUT	Settled asset not in acceptedAssets.	Use correct route.
S3	WRONG_PAYTO	Funds not sent to merchant’s payTo.	Re-route to correct address.
R1	REFUND_REQUIRED	Merchant indicates refund path (see refunds subprotocol).	Follow refund flow.