> ## Documentation Index
> Fetch the complete documentation index at: https://dev.bloombot.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error envelope and every API and deploy error code.

All errors use a uniform envelope:

```json theme={null}
{
  "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.                                                 |