Swap API Errors Reference

Use this page when a Carbium Swap API request fails before a signed transaction reaches Solana.

The fastest way to debug Swap API errors is to identify the layer first:

This page owns the pre-sign failure lane. Use Executing Swaps once a transaction payload exists, and use RPC Errors Reference after the signed transaction is sent through RPC.

Part of the Carbium Solana infrastructure stack.

First isolate the surface

Carbium's current docs expose two request families. Most avoidable errors come from mixing them.

If you send fromMint to Q1, or src_mint to a v1 path, fix the request shape before changing route, slippage, token pair, or provider. Use Swap API Request Families when you need the full v2 vs v1 map.

Authentication failures

Every Swap API request should send the Swap API key in the X-API-KEY header.

Verified public response bodies:

{"error":"API key missing"}

{"error":"Invalid API key"}

Do not put the Swap API key in frontend code. If you are unsure which key is being used, start from Get your API key and Carbium Auth Matrix. RPC keys and Swap API keys are separate.

Request-shape failures

Before treating an error as a route or liquidity problem, confirm the request is internally consistent.

Q1 request checklist

A Q1 quote request should look like this:

curl --request GET \
  --url 'https://api.carbium.io/api/v2/quote?src_mint=So11111111111111111111111111111111111111112&dst_mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount_in=1000000&slippage_bps=50' \
  --header 'X-API-KEY: YOUR_API_KEY'

Check these fields first:

Older v1 request checklist

Older v1 quote and swap paths use fromMint, toMint, amount, and slippage. The v1 swap path also requires owner and provider.

Keep the whole request on one family. A request that mixes Q1 fields with v1 fields is not a reliable test of route availability.

Route and pool lookup failures

The published Carbium quote and swap references document this 400 response for route-building failures:

{ "error": { "message": "No pool found" } }

The All Quote guide also shows provider-level route misses inside a broader response:

{
  "meteora-dlmm": {
    "error": "Could not find any route",
    "error_code": "COULD_NOT_FIND_ANY_ROUTE"
  }
}

Treat these as route diagnostics, not authentication diagnostics.

A route miss does not prove the whole API is down. It usually means the requested pair, size, provider, pool hint, or route source does not resolve cleanly.

Missing txn on Q1

Q1 can work as both a quote-only surface and a transaction-build surface. The difference is user_account.

Executable Q1 request shape:

curl --request GET \
  --url 'https://api.carbium.io/api/v2/quote?src_mint=So11111111111111111111111111111111111111112&dst_mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount_in=1000000&slippage_bps=50&user_account=YOUR_WALLET' \
  --header 'X-API-KEY: YOUR_API_KEY'

If your integration expects quote-only behavior, omit user_account. If it expects an executable payload, require user_account and fail fast when txn is empty.

When to leave this page

Move out of Swap API error triage when the API returned a transaction payload and the next failure happens after that.

The boundary matters because rebuilding a quote will not fix a signer bug, and changing RPC endpoints will not fix a missing X-API-KEY header.

Support payload

When you need help, preserve the smallest useful evidence set:

• endpoint path and request family, without secrets
• HTTP status and response body
• token mints, raw amount, slippage, provider, and pool hint if used
• whether user_account was included
• whether the response contained txn
• timestamp and environment
• transaction signature only if the flow reached RPC submission

Redact X-API-KEY, private keys, wallet seed phrases, and any full backend secret values before sharing logs.

For new builds, start with Q1, keep keys backend-side, and use this page only until you know whether the failure is auth, request shape, routing, or transaction payload generation.