Errors

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` array is empty.
`INVALID_REQUEST`	400	A required field is missing or has an invalid value. `details` names the field.
`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.
`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 but with deploy-specific codes:

Code	HTTP	Description
`INVALID_REQUEST`	400	A deploy request field is missing or invalid.
`INVALID_AUTH_TOKEN`	401	The auth token was rejected.
`INVALID_IMAGE_URL`	400	`image_url` must start with `http`.
`INVALID_BUNDLE_MODE`	400	`bundle_mode` must be `packed`, `non_packed`, or `sniper`.
`DUPLICATE_DEX`	400	A DEX appears more than once in `configs`.
`INVALID_DEX_CONFIG`	400	A DEX configuration entry is invalid. `message` includes the index and reason.
`INVALID_WALLET_ADDRESS`	400	`wallet_address` is not a valid Solana address or is not owned by the caller.
`INVALID_BUY_WALLET`	400	A wallet in `buys` is invalid.
`INVALID_DISTRIBUTION_WALLET`	400	A wallet in `distributions` is invalid.
`INSUFFICIENT_BALANCE`	400	A wallet has insufficient SOL balance. `message` includes the wallet, have, and need values in lamports.
`DISTRIBUTION_PERCENTAGE_EXCEEDS_CAP`	400	The total distribution percentage exceeds 100 %.
`DISTRIBUTIONS_REQUIRE_CREATOR_BUY`	400	You must set `creator_buy_sol_amount` when using distributions.
`NON_PACKED_TOO_MANY_BUYS`	400	`non_packed` mode has a maximum number of buyer wallets.
`BAGS_DESCRIPTION_REQUIRED`	400	A description is required for Bags launches.
`BAGS_FEE_CLAIMER_BPS_INVALID`	400	Bags fee claimer basis points must total 10,000.
`BUNDLE_SIMULATION_FAILED`	400	Bundle simulation failed before submission. `message` includes the DEX index.
`INTERNAL`	500	The server could not complete the deploy. Safe to retry.

Getting Started

Core Concepts

API errors

Deploy errors

​API errors

​Deploy errors

API errors

Deploy errors