Errors - Bloom API

All errors use a uniform envelope:

{
  "success": false,
  "error": {
    "code": "UPPER_SNAKE_CODE",
    "message": "Human-readable description.",
    "details": "Optional extra context."
  }
}

details is omitted when absent. The API uses a minimal HTTP status scheme — 400 for request errors, 401 for auth failures, 429 for rate limiting, and 500 for server errors. The precise error is always in the error.code field.

API errors

These apply to /api/v1/swap and general auth/rate-limit handling.

Code	HTTP	When
`UNAUTHORIZED`	401	Missing, malformed, unknown, or revoked Bearer token.
`RATE_LIMITED`	429	One or more rate-limit windows exhausted. `Retry-After` header present; `details` contains `retry_after=<seconds>`.
`WALLET_NOT_OWNED`	400	A wallet address in the request does not belong to your account. `details` contains the offending address.
`NO_WALLETS`	400	`wallets` is an empty array, or it was omitted and none of your wallets has spot trading enabled.
`INVALID_REQUEST`	400	A required field is missing or has an invalid value. `details` names the field. Also returned when a builder fee cannot be applied; `message` says why.
`LIQUIDITY_OUT_OF_RANGE`	400	Pool USD liquidity is outside the requested `min_liquidity`/`max_liquidity` band.
`MARKET_CAP_OUT_OF_RANGE`	400	Token USD market cap is outside the requested `min_market_cap`/`max_market_cap` band.
`TAX_OUT_OF_RANGE`	400	EVM host only. The token’s probed buy/sell tax exceeds your `max_tax` cap. `details` contains the probed and allowed values. The probe is best-effort; see the `max_tax` field on the swap request.
`TOKEN_OR_POOL_NOT_FOUND`	400	The token mint or pool address could not be resolved.
`NO_ROUTE`	400	No swap route could be found for the token/pool.
`INSUFFICIENT_BALANCE`	400	The wallet has insufficient balance for the swap.
`INTERNAL_ERROR`	500	The server could not complete the request. Safe to retry.

Deploy errors

/api/v1/deploy uses the same { success, error: { code, message, details? } } envelope, with its own set of codes. Both hosts serve deploys, but a few codes are specific to one of them.

Code	HTTP	Solana	EVM	Description
`UNAUTHORIZED`	401	✓	✓	Your Bearer token is missing, malformed, unknown, or revoked.
`RATE_LIMITED`	429	✓	✓	A rate-limit window is exhausted. Honour `Retry-After`.
`INVALID_REQUEST`	400	✓	✓	A field is missing or invalid. On EVM this also covers Solana-only fields, an unsupported `chain`, and malformed wei values.
`INVALID_AUTH_TOKEN`	401	✓	✓	A server-side credential was rejected, not yours. Rotating your API key will not help — report it.
`INVALID_IMAGE_URL`	400	✓	✓	`metadata.image_url` is empty or is not an `http(s)://` URL.
`INVALID_BUNDLE_MODE`	400	✓	✓	`bundle_mode` is not a valid value. `sniper` is Solana only. On EVM, also returned when `buys` is sent without a `bundle_mode`.
`DUPLICATE_DEX`	400	✓	✓	A `dex` appears more than once in `configs`.
`INVALID_DEX_CONFIG`	400	✓	✓	A `configs` entry is invalid; the message names its index. On EVM this also covers a `dex` that is not allowed on the selected `chain`, and rejections from the launchpad itself.
`INVALID_WALLET_ADDRESS`	400	✓	✓	`wallet_address` is malformed, or a creator or buy wallet is not owned by your account. Deploy does not use the swap host’s `WALLET_NOT_OWNED`.
`INVALID_BUY_WALLET`	400	✓	✓	A wallet in `buys` is malformed.
`INVALID_DISTRIBUTION_WALLET`	400	✓	✓	A wallet in `distributions` is malformed. On EVM, also when it is the creator wallet.
`INSUFFICIENT_BALANCE`	400	✓	✓	A wallet cannot cover the deploy. Solana’s message includes the wallet, have, and need in lamports; the EVM message carries no amounts.
`DISTRIBUTION_PERCENTAGE_EXCEEDS_CAP`	400	✓	✓	Distribution percentages total more than 10000 bps.
`DISTRIBUTIONS_REQUIRE_CREATOR_BUY`	400	✓	✓	`distributions` was sent without a creator buy — set `creator_buy_sol_amount` on Solana, or a non-zero `creator_buy_wei` on EVM.
`NON_PACKED_TOO_MANY_BUYS`	400	✓	✓	`non_packed` mode exceeds its buyer-wallet cap. Use `packed` or send fewer buys.
`BAGS_DESCRIPTION_REQUIRED`	400	✓	—	A Bags launch needs `metadata.description`. Always send one.
`BAGS_FEE_CLAIMER_BPS_INVALID`	400	✓	✓	The Bags fee split is invalid. Solana: `fee_claimers` bps must total 10000. EVM: `claimers` and `percent` must be the same length and `percent` must total 100.
`BUNDLE_SIMULATION_FAILED`	400	✓	✓	Simulation failed before submission. Check buy amounts, the fee split, and balances.
`INTERNAL`	500	✓	✓	The server could not complete the deploy. Safe to retry.

Deploy validation stops at the first failure, so an error describes one problem even when several exist. Fix the one you are given and resend.