Errors
Every failure returns a JSON body with an error field and a status code that identifies the failure class. Check the HTTP status code first, then read the error message.
Error format
All error responses are JSON objects with a single error field describing the specific problem:
{ "error": "no swap route found for the requested pair and amount" }The status code alone tells you the failure class — whether to fix the request, retry, or give up — without parsing the message.
Status codes
400Bad RequestA required parameter is missing or has an invalid format (e.g., non-hex address, non-numeric amount).
403ForbiddenA parameter combination is not allowed (e.g., a convenience fee above 10%, a missing
convenienceFeeRecipient, or an invalid fee-exempt key).
404Not FoundThe requested chain_id is not supported. Returns an nginx 404 HTML page — the only error without a JSON body. A 404 always means a wrong URL, never "no route found".
422Unprocessable EntityThe request is valid but cannot be fulfilled: no swap route exists (unknown token, insufficient liquidity, no profitable arbitrage) or the found route reverted in on-chain simulation. The message names the cause. Retrying with the same inputs will not help; changing the pair or amount might.
500Server ErrorUnexpected server error.
502Bad GatewayThe RPC node backing the on-chain simulation failed. Safe to retry.
503Service UnavailableThe service cannot serve the request right now: the liquidity state is behind the requested
minimumBlock, or the server is overloaded. Retry after a short delay.
504Gateway TimeoutThe request timed out before routing finished. Safe to retry.
Example bodies
{ "error": "amount must be provided" }
{ "error": "src and dst must be valid 0x... addresses" }
{ "error": "no swap route found: no known liquidity for src token 0x..." }
{ "error": "swap route found but its on-chain simulation reverted: revert: ..." }A 200 from the swap endpoint always contains a usable route — non-zero toAmount and a tx
object. Earlier API versions returned 200 with toAmount: "0" and no tx when no route was
found; that behavior is gone, so clients checking those fields keep working, but the reliable
signal is now the status code. See Get Swap Route.