Error recovery - XOXNO Docs

Check the HTTP status and retain the full response body. Errors from the aggregator itself return { "code": "...", "error": "..." }. Branch on code, which is a stable category; the error text is for humans and may change. Responses from an intermediary, such as a proxy or gateway, can have a different shape, so check the HTTP status first.

Error codes

HTTP	`code`	Meaning	Recovery
400	`invalid_request`	Bad token ID, bad amount, both or neither of `amount_in` and `amount_out`, or `sender` without `slippage`.	Fix the request. Do not retry it unchanged.
404	`no_route`	The router found no path between the tokens.	Try another pair or amount.
409	`snapshot_stale`	Only with `fresh=true`: the indexed snapshot is more than two ledgers behind the live ledger.	Retry with backoff. Discard any earlier executable quote.
422	`simulation_failed`	The server-side simulation rejected the transaction, for example because it exceeded the budget.	Lower `max_hops` or `max_splits` and request a new quote.
422	`minimum_output_unreachable`	The routed output is below the required minimum, for example after a smaller fallback route.	Request a new quote. Accept more slippage only with the user’s consent.
502	`upstream_error`	Stellar RPC was unreachable while preparing the transaction.	Retry with backoff.
503	`router_unavailable`	A `sender` was supplied but the deployment has no aggregator router configured.	Check `/api/v1/config`; `router` is `null` when this applies. Quotes without `sender` still work.
500	`internal_error`	The service failed to build the payload.	Retry once, then report it.

Recovery by symptom

Failure	Recovery
Invalid token or amount	Use catalog C-strkeys and exactly one atomic integer-string amount. Check decimals and argument bounds.
Unsupported platform	Use `aggregator`, or omit the platform argument.
Missing or invalid execution slippage	Provide an explicit valid tolerance before requesting an executable result.
No route	Try a different pair or amount; catalog membership does not guarantee connectivity or sufficient liquidity.
Stale snapshot	Retry with backoff after the snapshot catches up. Discard the old executable quote.
Simulation or budget failure	Inspect the error. A smaller route may help, but preserve the accepted minimum output and request a new quote.
Referral failure	Verify the referral lookup and deployment. Correct the ID before preparing another transaction.
Rate limit or temporary service failure	Back off, bound concurrency, and avoid polling on every render.

Do not turn a failed executable quote into a signable transaction by ignoring simulation errors. Pricing without a sender is useful for an estimate, not proof that the route can execute.

After submission

Distinguish RPC acceptance from successful on-chain execution. For uncertain responses, look up the transaction hash before retrying. Refresh the account sequence for a new transaction. A slippage failure requires a new quote and user decision. Do not silently increase tolerance. For a multi-transaction liquidity plan, inspect which steps succeeded and continue from the asset actually held.

Report an issue

Include timestamp, deployment, request arguments, HTTP status, complete response body, and transaction hash when available. Record the snapshot or simulation ledger and the returned fallback metadata. Never include secret keys or seed phrases. Integration guide · Quote phases

​Error codes

​Recovery by symptom

​After submission

​Report an issue

Error codes

Recovery by symptom

After submission

Report an issue