{ error: { code, message, details? }, meta }. Branch on the stable code,
because the human-readable message may change.
| Code | HTTP | Meaning |
|---|---|---|
INVALID_REQUEST | 400 | The body or params failed validation. The details field lists the fields. A chain ID RAVN doesn’t support is one of them (details.fieldErrors names the field). |
UNSUPPORTED_TOKEN | 400 | The token is not resolvable on that chain. |
NO_LIQUIDITY | 404 | No venue could quote this pair or amount. |
NOT_FOUND | 404 | The resource doesn’t exist for this caller, for example PATCH /v1/keys feeBps on a non-self-serve key. |
QUOTE_EXPIRED | 410 | The quoteToken is past its expiresAt (the primary quote’s, or that alternative’s own) and the route, priced again, no longer meets the minimum it showed (or the venue didn’t answer, or it’s more than 10 minutes late, or the quote holds no minimum); or RAVN no longer holds the quote. Request a new quote. |
QUOTE_INVALID | 400 | The quoteToken is malformed or tampered. |
QUOTE_NOT_EXECUTABLE | 400 | The quoteToken decodes fine but is a preview only (executable: false on the quote). details.missing lists what it was priced without (destinationAddress, refundAddress, or both): request a fresh quote with them. Empty when the preview has another cause, such as a wallet holding less than the amount. |
ORDER_REJECTED | 422 | /submit-signature: the venue refused the order, and message carries its reason. A duplicate-order refusal means an earlier submit went through, so don’t sign a new one. /submit-transaction: Solana’s preflight refused the transaction, or Jupiter refused it and it hasn’t landed, so nothing was sent. |
RATE_LIMITED | 429 | Your tier’s rate limit was exceeded (see Authentication). Retry after details.retryAfterSec, also sent as a Retry-After header. /status polls have a budget of their own. |
UNAUTHORIZED | 401 | A presented x-api-key doesn’t match any known key. No key at all is fine, that’s the anonymous tier. |
FORBIDDEN | 403 | A public key where the secret key is needed (PATCH /v1/keys, POST /v1/keys/secret), or a public key used from a site outside its allowedOrigins. See Public and secret keys. |
BUILD_FAILED | 502 | /execute: the swap couldn’t be built right now. /submit-signature: the venue errored on the order, and it may still have been placed: check before signing a new one. /submit-transaction: Solana or Jupiter couldn’t be reached, or Jupiter couldn’t confirm the swap landed, and the transaction may already have been sent: retry with the same signedTransaction before signing a new one. |
VENUE_RATE_LIMITED | 503 | /execute or /submit-signature: the venue is rate-limiting RAVN. Retry the same call after details.retryAfterSec. |
UNAVAILABLE | 503 | RAVN can’t check API keys right now (its key store is unreachable; your key is fine), or can’t look up a quoteToken from /quote right now. Retry the same call after details.retryAfterSec (also the Retry-After header, for the key store). |
NOT_CONFIGURED | 503 | The endpoint isn’t set up on RAVN’s side yet, for example x402 before its payout address is configured. Try again later. |
INTERNAL | 500 | An unexpected or venue-side error occurred. |
{
"error": {
"code": "NO_LIQUIDITY",
"message": "No liquidity available for this pair/amount",
"details": {
"routeType": "EVM_CROSS_CHAIN",
"eligibleVenues": ["across", "relay", "mayan"],
"excludedVenues": []
}
},
"meta": { "requestId": "6b50...19e", "version": "2024-01" }
}
Debugging
NO_LIQUIDITY: read details before assuming it’s a real liquidity gap.
eligibleVenues is every venue that could serve this chain pair, computed before your own
excludeVenues is applied; excludedVenues echoes back what you passed, plus every venue your
onlyVenues left out. If eligibleVenues is non-empty but you also passed excludeVenues or
onlyVenues, you may have excluded every venue that could have
served the route yourself. Both lists also cover the steps of multi-step routes, whose venues
eligibleVenues doesn’t name: leaving out one step’s venue drops that route. A route through
Bitcoin-source THORChain specifically drops out of
eligibleVenues whenever THORChain’s HALTMEMOLESS flag is set, see
Supported Chains & Venues, while Chainflip, Relay, and NEAR Intents stay
unaffected for the same pair.Always log the
requestId from meta, which is also in the x-request-id header. Include it
when you contact support and we can trace the exact request.