> ## 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 MultiversX Aggregator pair, quote, rate limit, and service errors.

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

## Error Body

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

Match the error string by substring. The API does not return a nested `code` field.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Quote returns 400 with unknown token_in or unknown token_out">
    **Cause:** `from` or `to` is not in the router token registry.

    **Fix:** Check the token identifier format and call [`/api/v1/pair-config`](/aggregator/pair-config). Stop if `supported=false`.

    **Verify:** Pair config returns `supported: true`, `decimalsIn`, `decimalsOut`, and `minAmountIn`.

    **Escalation data:** Full request URL, token identifiers, and pair-config response.
  </Accordion>

  <Accordion title="Quote returns 400 with no path between tokens">
    **Cause:** Both tokens are known, but the current pool graph has no route.

    **Fix:** Show the pair as unavailable. Requote only after token or liquidity state changes.

    **Verify:** `/api/v1/pair-config` returns `supported=false` with the route error.

    **Escalation data:** `from`, `to`, timestamp, and pair-config response.
  </Accordion>

  <Accordion title="Quote returns 400 for invalid amount">
    **Cause:** Amount is missing, negative, fractional, zero, non-numeric, or sent in human-readable units.

    **Fix:** Send exactly one of `amountIn` or `amountOut` as an integer string in the token's smallest unit.

    **Verify:** The amount is greater than or equal to `minAmountIn` from pair config.

    **Escalation data:** Query string, token decimals, and UI amount before conversion.
  </Accordion>

  <Accordion title="Quote returns 400 for both or missing amount fields">
    **Cause:** The request has both `amountIn` and `amountOut`, or neither.

    **Fix:** Use `amountIn` for forward quotes or `amountOut` for reverse quotes.

    **Verify:** The final query string contains exactly one amount field.

    **Escalation data:** Full request URL.
  </Accordion>

  <Accordion title="Quote returns 422 during transaction construction">
    **Cause:** Route simulation, nonce fetch, gas estimation, or transaction construction failed.

    **Fix:** Retry without `sender` for display pricing. For signing flows, lower `maxSplits` or `maxHops`, then requote with `sender`.

    **Verify:** Quote without `sender` returns `amountOut`; quote with lower route caps returns `transaction` or `txData`.

    **Escalation data:** Request URL, sender, route caps, and response body.
  </Accordion>

  <Accordion title="HTTP 429 rate limit exceeded">
    **Cause:** The client exceeded 100 requests per second from one IP.

    **Fix:** Add a client-side queue and exponential backoff. Keep `includePaths=false` for price polling.

    **Verify:** Request rate drops below 100 req/s per IP and 429 responses stop.

    **Escalation data:** Request rate, IP range, timestamps, and response headers.
  </Accordion>

  <Accordion title="HTTP 503 service unavailable">
    **Cause:** The service is warming up or the pool snapshot is unavailable.

    **Fix:** Retry with backoff. Do not sign stale transaction data from a previous quote.

    **Verify:** `/health` returns healthy and a new quote succeeds.

    **Escalation data:** `/health` response, timestamp, request URL, and response body.
  </Accordion>
</AccordionGroup>

## Related Pages

* [Quote endpoint](/aggregator/quote)
* [Pair config](/aggregator/pair-config)
* [Token amounts](/resources/token-amounts)
* [Quote freshness](/resources/quote-freshness)