> ## Documentation Index
> Fetch the complete documentation index at: https://xoxno.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Error reference

> Troubleshoot Stellar Aggregator token, quote, snapshot, simulation, and rate limit errors.

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

## Error Body

```json theme={"system"}
{
  "error": "<message>"
}
```

Some failures include extra fields such as `degraded`, `requestedMaxSplits`, or snapshot ledger data. Log the full response body.

## Troubleshooting

<AccordionGroup>
  <Accordion title="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`](/stellar-aggregator/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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related Pages

* [Quote endpoint](/stellar-aggregator/quote)
* [Tokens endpoint](/stellar-aggregator/tokens)
* [Execution planes](/stellar-aggregator/execution-planes)
* [Quote freshness](/resources/quote-freshness)