Status & errors

An API error and a swap's status are different things. An error means the request itself was rejected before or during preparation, so surface it immediately. A status tracks the lifecycle of a swap that was already accepted, so poll it over time instead.

Status lifecycle

Poll GET /api/swap/status/{swapId} for a focused view of one swap, its settlement breakdown plus any cross-chain repayment jobs it carries. The top-level status field takes one of three values.

• UNKNOWN means this server hasn't seen the swap yet
• SETTLED_DST means the swap itself settled and its cross-chain repayment jobs are still in flight
• COMPLETE means the swap settled and every repayment job reached settled

A same-chain swap carries no repayment jobs, so it moves straight from UNKNOWN to COMPLETE once settlement lands. A cross-chain swap passes through SETTLED_DST while the repayment side catches up.

Each repayment job in the response carries its own finer-grained status, moving through pending, bridging, bridge_submitted, delivered, and settling on its way to settled, with failed as a terminal off-ramp.

A repayment job that reaches failed does not flip the swap's top-level status to a terminal state on its own, so treat a SETTLED_DST swap whose repayment jobs include a failed entry as needing attention rather than assuming it will eventually reach COMPLETE.

Polling for status

Poll GET /api/swap/status/{swapId} (see the Swaps group in the API Reference) rather than guessing completion from your own timers. As a recommended cadence, start at 2-3 second intervals immediately after submission, back off to 10-15 seconds while repayment jobs are in flight, and stop polling once you observe COMPLETE. Cross-chain swaps can legitimately sit in SETTLED_DST for the underlying bridge's full settlement window, so do not treat that alone as a failure signal, check the repayment jobs for a failed entry instead.

Telling an error from a status

• A 4xx response to /quote or /prepare means the request was rejected outright, so nothing was created. Fix the request per the API overview's Errors section and resubmit.
• A 5xx response, or a transient network error, is retryable. Retry the same request with exponential backoff (a few hundred ms, doubling, capped) rather than failing the user's flow on the first attempt.
• A swap that was accepted (you got back a swap id) but whose repayment jobs later report failed is a status outcome, not an API error, meaning the request was valid but a repayment leg didn't complete. Read the failing job's entry in repaymentJobs for detail before treating it as opaque.

Retry guidance

• Never retry a 4xx response unchanged, since it will fail again identically.
• Only mark a swap successful once its status is COMPLETE, never on SETTLED_DST.
• /quote and /prepare do not mutate state, so retrying either is always safe.

User messaging

Prefer messages like these.

• "Preparing swap..."
• "Settling..."
• "Waiting on cross-chain repayment..." (cross-chain only)
• "Done"

Avoid exposing internal component names, infra details, or raw error codes in user-facing copy. Map the machine-readable error code (see the API overview's Errors section) to a short human sentence instead.