Error Codes

All error responses use the same format:

{
  "success": false,
  "error": "error message"
}

HTTP status codes

Code	Meaning	When
`200`	Success	Request processed successfully
`400`	Bad Request	Invalid parameters, missing required fields, or a route the on-chain program cannot execute (multi-hop ExactOut, ExactOut on a non-Valiant pool)
`401`	Unauthorized	No API key was provided
`403`	Forbidden	The key is invalid, disabled, or revoked — blocked by the key’s origin allowlist — or a `quoteId` issued to a different key
`404`	Not Found	No route or pool found for the given parameters, or pools exist without enough liquidity
`409`	Conflict	Firm-quote redemption failed: the pinned route is gone, or the price drifted past the firm margin
`410`	Gone	The `quoteId` expired (or is unknown) — request a fresh quote
`422`	Unprocessable Entity	The route was found but cannot be executed as one transaction — too many accounts, or a split route on the CPI endpoint
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server issue. A failed simulation is not a 500 — it returns inside a `200` as `simulation.success: false`

API errors

Authentication errors (all `/api/v1/*` endpoints)

Error message	HTTP	Cause
`missing api key`	401	No `Authorization: Bearer` header or `?key=` parameter was sent
`invalid api key`	403	The key doesn’t exist, is disabled, or was revoked
`origin required for this api key`	403	The key has an origin allowlist and the request sent no `Origin`/`Referer`
`origin not allowed for this api key`	403	The request’s origin isn’t on the key’s allowlist
`rate limit exceeded`	429	Too many requests — see Rate limits

Quote errors (`GET /api/v1/quote`)

Error message	HTTP	Cause
`invalid inputMint`	400	`inputMint` is not a valid base58 public key
`invalid outputMint`	400	`outputMint` is not a valid base58 public key
`invalid amount`	400	Amount is not a valid positive number
`invalid swapMode`	400	`swapMode` must be `ExactIn` or `ExactOut`
`no route found`	404	No viable swap path exists
`no pool found for token pair`	404	No liquidity pool exists for one of the required hops
`no route found: insufficient liquidity`	404	Pools exist but don’t have enough liquidity. Match the full string — the wire value is prefixed with `no route found:`

Swap errors (`POST /api/v1/swap`)

Error message	HTTP	Cause
`invalid userWallet address`	400	`userWallet` is not a valid base58 public key
All quote errors above	400/404	Same causes as quote endpoint
`multi-hop ExactOut is not supported on-chain; ...`	400	ExactOut works on a single hop only — use the ExactIn-with-buffer pattern the message describes
`ExactOut is only supported on Vortex pools; ...`	400	The route crosses Fluxbeam or Moonit, whose CPIs have no exact-out mode. Re-quote as ExactIn or set `excludeDexes`
`the best route needs more accounts than fit in one transaction; ...`	422	Constrain routing (`maxHops`, `excludeDexes`) or split the trade
`failed to build transaction`	500	Internal error building the transaction

A failed simulation is not an error status. The request returns 200 with simulation.success: false and the failure detail in the body — check that field rather than the HTTP status.

GET /quote will return an ExactOut quote over a Fluxbeam or Moonit route, because the DEX restriction is enforced when the transaction is built, not when the route is priced. Handle the 400 at /swap or /instructions rather than assuming a successful quote implies an executable ExactOut swap.

Instructions errors (`POST /api/v1/instructions`)

Error message	HTTP	Cause
`invalid userWallet address`	400	`userWallet` is not a valid base58 public key
All quote errors above	400/404	Same causes as quote endpoint
`multi-hop ExactOut is not supported on-chain; ...`	400	Single-hop ExactOut only
`ExactOut is only supported on Vortex pools; ...`	400	Route crosses a DEX with no exact-out CPI
`the best route needs more accounts than fit in one transaction; ...`	422	Too many accounts for one transaction
`pool data unavailable`	404	Pool account data unavailable (temporary)
`failed to build instructions`	500	Internal error building the instructions

Firm-quote errors (`POST /api/v1/swap`, `POST /api/v1/instructions` with `quoteId`)

Error message	HTTP	Cause	Recovery
`quote expired: request a fresh quote`	410	The `quoteId` is past `validForMs` (or past `firmForMs` when `firm: true`), was evicted, or never existed	Fetch a fresh quote and retry with the new `quoteId`
`quoted route is no longer available: request a fresh quote`	409	The pinned route’s pool disappeared — or, with `firm: true`, the price drifted past the firm margin	Fetch a fresh quote; with `firm`, retry immediately (the window is short)
`quoteId was issued to a different api key`	403	The quote was minted under another API key	Re-quote with your own key
`request does not match the quoted pair, amount, or swap mode`	400	The swap request’s pair/amount/swapMode differ from the original quote	Send the exact quoted request, or drop `quoteId`
`firm redemption requires a quoteId`	400	`firm: true` without a `quoteId`	Include the `quoteId` from the quote you’re redeeming

See Firm quotes for how quoteId and firm work.

Simulation result errors

When skipSimulation is false, the swap response includes a simulation object:

Field	Type	Meaning
`success`	boolean	Whether simulation passed
`error`	string	Error message if simulation failed
`insufficientFunds`	boolean	Wallet doesn’t have enough balance
`slippageExceeded`	boolean	Price moved beyond tolerance
`computeUnitsConsumed`	integer	Compute units (CU) used during simulation
`logs`	string[]	Program log output

On-chain errors

These surface after a signed transaction is submitted — in the transaction’s error and program logs, not in an HTTP response. They come from two sources: the Vulcx aggregator program itself, and the Solana runtime / SPL Token program underneath it.

Vulcx aggregator program errors

Anchor custom errors from program Vu1cUxynmbPUsFqVz51FJJ2y69vX2yrkTS13ajomd9D. In a failed transaction they appear as Custom(<code>) on the aggregator instruction and by name in the program logs.

Code	Error	Cause	Recovery
`6006`	`SlippageExceeded`	Output fell below the transaction’s `min_out` between build and execution	Get a new quote and rebuild — or use firm quotes to pin the price
`6007`	`InvalidPoolDiscriminator`	A routed pool account isn’t a genuine pool (migrated or spoofed)	Re-quote; the pool set may have changed
`6009`	`MintMismatch`	A token mint doesn’t match the pool it was routed through	Re-quote
`6010`	`TokenOwnerMismatch`	A token account’s owner doesn’t match the expected authority	Verify `userWallet` and the token accounts you signed
`6003`	`MathOverflow`	Arithmetic overflowed — typically an extreme amount	Reduce the trade size
`6002` / `6005`	`InvalidOwner` / `InvalidTokenAccount`	An account passed to the program has the wrong owner or malformed data	Rebuild from a fresh quote rather than hand-editing accounts
`6011`	`PercentOverflow`	Split allocations for an input token exceed 100%	Engine-built transactions never do this — rebuild from a quote
`6016` / `6017` / `6001`	`TooManyHops` / `TooManyAccounts` / `InsufficientAccounts`	Hop or account counts outside program limits	The engine normally prevents this (`422` at build). Constrain with `maxHops` / `excludeDexes`
`6008`	`ExactOutMultiHopNotSupported`	ExactOut over more than one hop	The engine pre-rejects this as `400` — single-hop ExactOut only
`6022`	`ExactOutUnsupportedSwapType`	ExactOut routed over Fluxbeam/Moonit, which have no exact-out CPI	The engine pre-rejects this as `400` — ExactOut is Valiant-only
`6019`–`6021`	`InvalidSessionAccount` / `MissingSessionProgramSigner` / `SessionRouteUnsupportedHop`	Session-signed swaps only: bad or expired session, missing session-signer PDA, or a non-Valiant hop in a session route	Applies to session flows; standard signed swaps never hit these

Administration and validation errors (6000 InvalidAmount, 6004 InvalidIndex, 6012–6015 InvalidFeeRecipient / FeeTooHigh / InvalidAdmin / ProtocolNotInitialized, 6018 InvalidStepCount) occur only on protocol-admin instructions or malformed hand-built transactions — not on engine-built swaps.

Solana runtime & SPL Token errors

These are not Vulcx program errors — they come from the network or the token program, so they carry no 6xxx code.

Error	Cause	Recovery
Blockhash not found / expired	The transaction wasn’t confirmed before its blockhash expired (~60s)	Rebuild with a fresh blockhash and resubmit
`insufficient funds` (SPL Token `0x1`)	The wallet’s balance dropped below the input amount after simulation	Verify balance, then retry
Account not found / account data too small	A required account (pool, associated token account) doesn’t exist or changed	Ensure token accounts exist; re-quote if a pool migrated

Overview

Endpoints

Error Codes

Error Codes

HTTP status codes

API errors

Authentication errors (all `/api/v1/*` endpoints)

Quote errors (`GET /api/v1/quote`)

Swap errors (`POST /api/v1/swap`)

Instructions errors (`POST /api/v1/instructions`)

Firm-quote errors (`POST /api/v1/swap`, `POST /api/v1/instructions` with `quoteId`)

Simulation result errors

On-chain errors

Vulcx aggregator program errors

Solana runtime & SPL Token errors

​Error Codes

​HTTP status codes

​API errors

​Authentication errors (all /api/v1/* endpoints)

​Quote errors (GET /api/v1/quote)

​Swap errors (POST /api/v1/swap)

​Instructions errors (POST /api/v1/instructions)

​Firm-quote errors (POST /api/v1/swap, POST /api/v1/instructions with quoteId)

​Simulation result errors

​On-chain errors

​Vulcx aggregator program errors

​Solana runtime & SPL Token errors

Error Codes

HTTP status codes

API errors

Authentication errors (all `/api/v1/*` endpoints)

Quote errors (`GET /api/v1/quote`)

Swap errors (`POST /api/v1/swap`)

Instructions errors (`POST /api/v1/instructions`)

Firm-quote errors (`POST /api/v1/swap`, `POST /api/v1/instructions` with `quoteId`)

Simulation result errors

On-chain errors

Vulcx aggregator program errors

Solana runtime & SPL Token errors