Error Body
degraded, requestedMaxSplits, or snapshot ledger data. Log the full response body.
Troubleshooting
Quote returns 400 for unknown input or output token
Quote returns 400 for unknown input or output token
Cause:
from or to does not resolve to a token in the current snapshot.Fix: Load /api/v1/tokens and use canonical token IDs. Avoid storing only short aliases such as USDC.Verify: The selected token exists in /api/v1/tokens and has degree > 0.Escalation data: Token ID, /api/v1/tokens response excerpt, and quote URL.Quote returns 400 for amount fields
Quote returns 400 for amount fields
Cause: Both
amount_in and amount_out were sent, neither was sent, or the amount is not a raw atomic unit string.Fix: Send exactly one amount field. Convert from human-readable amount with the token’s decimals.Verify: The query string has one amount field and no decimal point.Escalation data: Query string, selected token decimals, and UI amount.Quote returns 404 no path
Quote returns 404 no path
Cause: The selected execution plane has no route between the tokens.Fix: Try another token pair or execution plane. Use
platform=aggregator for Soroban composition and platform=all only for direct-user route selection.Verify: The same request with a supported pair returns non-zero amountOut.Escalation data: from, to, platform, and timestamp.Quote returns 409 snapshot_stale
Quote returns 409 snapshot_stale
Cause:
fresh=true requested a freshness gate and the snapshot ledger drift exceeded the service threshold.Fix: Retry after the snapshot catches up. Do not sign an envelope from an older quote.Verify: A later request with fresh=true succeeds, or the response ledger drift is within threshold.Escalation data: Response body, live ledger, snapshot ledger, and timestamp.Quote returns 422 Budget, ExceededLimit
Quote returns 422 Budget, ExceededLimit
Cause: Soroban simulation rejected the route because the envelope exceeded budget.Fix: Lower
maxSplits or maxHops, then requote. If the response includes degraded, surface the reduced route to the user.Verify: A quote with lower route caps returns transaction.envelopeXdr.Escalation data: Request URL, maxSplits, maxHops, platform, and full response body.Quote returns 422 for referral or simulation failure
Quote returns 422 for referral or simulation failure
Cause:
referralId is not registered, the simulator rejected the envelope, or upstream RPC returned a simulation error.Fix: Remove or correct referralId. If the route still fails, retry without sender for display pricing and block signing.Verify: Quote without referral succeeds, or quote without sender returns pricing only.Escalation data: referralId, sender, response body, and request timestamp.HTTP 429, 502, or 503
HTTP 429, 502, or 503
Cause: Rate limit, upstream RPC failure, service warmup, or snapshot unavailability.Fix: Apply exponential backoff. Queue requests per user action instead of polling every render.Verify: Retries stop after a successful quote and request rate remains below 100 req/s per IP.Escalation data: Status code, response body, retry count, and timestamps.