Swap API Errors Reference

Use this page when a Carbium Swap API request fails before a signed transaction reaches Solana. It covers the currently documented error lane for:

• missing or invalid API authentication
• quote or swap requests that cannot find a route or pool
• executable quote requests that return no txn

This page does not cover on-chain transaction failures after signing and submission. For that stage, move to your RPC confirmation flow and application logs.

Part of the Carbium Solana infrastructure stack.

What this page owns

Carbium's current docs expose two request families:

This page only covers failures that are directly documented on those surfaces. It does not invent a broader error taxonomy.

Fast triage

Check these first before you debug deeper:

1. Send X-API-KEY on every Swap API request.
2. Use the parameter names that match the endpoint family you chose.
3. Send token amounts in smallest units.
4. If you need an executable transaction from Q1, include user_account.
5. If a route is missing, validate the token pair, provider, and optional pool hint before retrying.

Auth failures

These are the quickest failures to identify.

Carbium's live API surface currently returns JSON errors in this shape:

{"error":"API key missing"}

{"error":"Invalid API key"}

If you are not sure which key you are sending, start from Get your API key and confirm you are using the Swap API key, not an RPC key.

Route and pool lookup failures

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

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

Carbium's all-quote guide also shows provider-specific route misses in the response body:

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

Use those messages as a routing diagnosis, not as an auth diagnosis.

What usually causes route failures

Do not treat a route miss as proof that the whole API is down. It usually means the requested pair, provider, or liquidity path does not resolve cleanly.

Missing txn on Q1 executable quotes

Carbium's current Q1 build path is GET /api/v2/quote. The execution guides document one key rule:

• if user_account is provided, the response can include a base64 txn
• if user_account is omitted, txn can be an empty string

That means an empty txn is usually a request-shape issue, not a signing failure.

What to check

Minimal 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 it is missing.

Parameter-family mistakes

Carbium's docs currently show both older v1 parameter names and the newer Q1 v2 names. Mixing them is a common integration mistake.

If you send src_mint to a v1 path or fromMint to a v2 path, debug the request shape before you assume Carbium returned a deeper product failure.

When the failure is no longer a Swap API problem

Move out of this page when:

• the quote or transaction payload was returned successfully
• you already signed the transaction
• the failure appears during send, confirmation, or finalization

At that point the problem has shifted to transaction execution, wallet signing, RPC reliability, or on-chain state.

🔶

Use Executing Swaps for the Q1 build flow, Q1 for the current quote surface, and Get your API key if the failure starts with authentication.