Error Codes

All error responses use the same format:

{
  "success": false,
  "code": "NO_ROUTE",
  "error": "no route found between tokens"
}

Branch on code, not on error. code is the contract: it is never renamed or reused for a different meaning once shipped, so a client that switches on it keeps working. error is the human sentence and may be reworded at any time — matching it means a copy edit on our side silently breaks your integration.New codes may be added, so treat one you do not recognise as its HTTP status class rather than failing closed. Some responses carry no code at all: the admin debug routes, and anything served before codes shipped.Do not branch on the HTTP status alone either. It is overloaded: 404 is “no pool”, “no route” and the disguised admin gate; 409 is both a drifted firm quote and a simulation that failed on slippage, which need different recoveries. The code separates them.

Codes

Code	HTTP	Meaning	Recovery
`INVALID_REQUEST`	400	Params or body failed validation	Fix the request
`INVALID_WALLET`	400	`userWallet`/`authority`/`sessionAccount` is not a valid pubkey	Fix the address
`FEE_CAP_EXCEEDED`	400	`platformFeeBps + integratorFeeBps` is over the 100 bps ceiling	Lower `integratorFeeBps`; the message names both rates
`FEE_NEEDS_REFERRER`	400	`integratorFeeBps` was set with no `referrer` to pay it to	Send a `referrer`, or drop the fee
`FEE_ABOVE_KEY_MAX`	400	`integratorFeeBps` is above the ceiling set on this API key in the portal	Lower the fee, or raise the key’s ceiling at portal.vulcx.xyz
`EXACT_OUT_MULTIHOP`	400	Exact-out cannot span hops on chain	Use the ExactIn-with-buffer pattern
`EXACT_OUT_DEX`	400	A hop’s venue has no exact-out CPI	Re-quote with `swapMode=ExactIn`
`SESSION_ROUTE_UNSUP`	400	The route has a hop that cannot forward the session signer	Retry without `sessionAccount`, or wait for a different route
`QUOTE_MISMATCH`	400	The `quoteId` does not match the pair, amount or mode sent with it	Send the same parameters you quoted
`SIM_INSUFFICIENT`	400	The build simulated and the wallet cannot cover it	Not retryable — fund the wallet
`MISSING_API_KEY`	401	No `Authorization: Bearer` and no `?key=`. Only `/api/v1/stream` can return this	Send a key
`INVALID_API_KEY`	403	The key does not exist, is disabled, or was revoked	Check the key
`ORIGIN_REQUIRED`	403	The key is origin-locked and no `Origin` was sent	Send from an allowed origin
`ORIGIN_NOT_ALLOWED`	403	The `Origin` is not on the key’s allowlist	Add it, or use a different key
`QUOTE_WRONG_KEY`	403	The `quoteId` was minted for a different API key	Redeem with the key that quoted
`STREAM_NOT_IN_PLAN`	403	`/api/v1/stream` upgrade on a plan that does not include the stream	Move to a plan with stream connections — see Rate limits
`NO_POOL`	404	No pool exists for the pair	Nothing to do — the pair is not listed
`POOL_DATA_MISSING`	404	Pools exist but their state is not loaded	Transient; retry shortly
`NO_ROUTE`	404	Pools exist, but no path connects the pair at this size	Try a smaller amount
`NO_ROUTE_CONSTRAINED`	404	A path exists, but not inside your constraints	Widen `allowedIntermediateMints`/`maxHops`, or drop them
`QUOTE_STALE`	409	A pinned route drifted past its firm margin	Re-quote and retry
`SIM_SLIPPAGE`	409	The build’s own simulation failed on slippage	Re-quote and retry — this is not a firm-quote failure
`QUOTE_EXPIRED`	410	The `quoteId` is past `validForMs` (3 s)	Re-quote
`ROUTE_TOO_LARGE`	422	More accounts than fit in one transaction	Constrain the route, or split the trade
`CPI_SPLIT_UNSUP`	422	Split routes have no CPI form yet	Use a pair that routes directly
`SIM_FAILED`	422	Simulation failed for some other reason	Inspect `data.simulation`
`RATE_LIMITED`	429	Bucket exhausted. Carries a `Retry-After` header	Back off — see Rate limits
`STREAM_LIMIT`	429	The account already holds its plan’s stream connections	Close a connection, or move to a larger plan
`INTERNAL`	500	Our fault	Retry; report it if it persists

On a /swap or /instructions rejection whose simulation failed, the result is attached at data.simulation. Its insufficientFunds and slippageExceeded booleans mirror SIM_INSUFFICIENT and SIM_SLIPPAGE.

HTTP status codes

Code	Meaning	When
`200`	Success	Request processed successfully
`400`	Bad Request	Invalid parameters, missing required fields, a route the on-chain program cannot execute (multi-hop ExactOut, ExactOut on a non-Valiant pool), or a `/swap` build whose simulation failed for insufficient funds
`401`	Unauthorized	No API key was provided. Only `/api/v1/stream` returns this — REST allows anonymous callers, so a keyless REST request is rate-limited, not rejected
`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. Also a `/swap` build whose simulation failed on slippage — the price moved after quoting, so re-quote and retry
`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, a split route on the CPI endpoint, or a `/swap` build whose simulation failed for any other reason
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server issue. A failed simulation is not a 500 — it is a `400`, `409` or `422`, depending on why

API errors

Authentication errors

Error message	HTTP	Cause
`missing api key`	401	No `Authorization: Bearer` header or `?key=` parameter was sent. Reachable only on `GET /api/v1/stream`, the one endpoint that always requires a key
`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. The response carries `Retry-After` — 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 Valiant pools; ...`	400	The route crosses Fluxbeam, whose CPIs have no exact-out mode. Re-quote as ExactIn
`the best route needs more accounts than fit in one transaction; ...`	422	Split the trade into smaller amounts. `maxHops` narrows the route on `POST /api/v1/cpi/route-accounts`; `/swap` and `/instructions` accept no routing constraints
`failed to build transaction`	500	Internal error building the transaction

A failed simulation is an error status. If POST /swap simulates the transaction and the simulation says it would fail, the response is a 400, 409 or 422 — never a 200 — and no transaction is returned, so there is nothing to accidentally sign.The simulation itself stays at data.simulation on the rejection, exactly where a successful response puts it, so code that already reads that field keeps working; it just has to stop treating 200 as the signal.Pass skipSimulation: true if you want the transaction regardless. Nothing simulates then, so nothing gates.

GET /quote will return an ExactOut quote over a Fluxbeam 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 Valiant 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` on `/cpi/route-accounts`, or split the trade
`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, which has 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

Codes

HTTP status codes

API errors

Authentication errors

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

​Codes

​HTTP status codes

​API errors

​Authentication errors

​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

Codes

HTTP status codes

API errors

Authentication errors

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