Skip to main content
Use this page to map Stellar Aggregator error symptoms to causes, fixes, and verification data.

​
Error Body

{
  "error": "<message>"
}
Some failures include extra fields such as degraded, requestedMaxSplits, or snapshot ledger data. Log the full response body.

​
Troubleshooting

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.
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.
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.
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.
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.
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.
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.