Handling Rejections & Error Codes - StellarX402

An agent that treats every payment failure the same way is an agent that either gives up too easily or burns money in a loop. This page maps every rejection code to a sensible reaction. For the wire-level definitions, see the Error & Rejection Codes reference.

Reaction table

Code	What it means	What to do
`insufficient_funds`	Wallet balance below required amount	Top up. Do not retry the same request until balance changes.
`authorization_expired`	`validBefore` elapsed before verify	Re-sign with a fresh authorization and retry once.
`amount_mismatch`	Signed amount does not match `PaymentRequirements`	Re-fetch `PaymentRequirements` (price may have changed) and re-sign.
`price_changed`	Server changed its price between quote and verify	Re-fetch and re-quote.
`network_mismatch`	Signed on wrong network	Fix wallet network. Not usually a transient error.
`asset_not_supported`	Facilitator does not settle in this asset	Do not retry. Choose another provider.
`resource_gone`	Endpoint is deprecated or removed	Drop from the queue. Do not retry.
`rate_limited`	Facilitator or seller throttling	Back off with jitter.
`settlement_failed`	On-chain submission failed	Retry after a short delay. If it persists, escalate.
`signature_invalid`	Client bug or wrong key	Do not retry. Fix client.
`unsupported_scheme`	Facilitator does not support the scheme requested	Choose another provider.

Idempotency

fetchWithPayment treats each attempt as independent. If you retry after a rejection, you sign a new authorization; the previous one is discarded, not “redeemed.”

What to log

At minimum, log the tuple (resource, code, amount, txHash?). Aggregating on code per-resource lets you spot degraded endpoints before your budget notices.

Backoff policy

A reasonable default:

Transient (settlement_failed, rate_limited): exponential backoff, 3 attempts, jitter.
Client-fixable (amount_mismatch, price_changed, authorization_expired): 1 immediate retry, then give up.
Terminal (resource_gone, asset_not_supported, signature_invalid, unsupported_scheme, network_mismatch): no retry.
Budget (insufficient_funds): no retry until the wallet’s balance changes.