# Known Behaviors

> Quirks of the current API to plan for, such as plain-text errors, 200 answers that carry a failure and status codes that differ by chain.

This page lists behaviors of the current API that can surprise an integration. Each one is also stated in the
reference entry of the endpoint concerned; this page gathers them so you can plan for them in one place.

They describe the API as it runs today, not a contract. Most are rough edges that may be smoothed out later, so
write code that tolerates both the current behavior and the documented intent.

## Errors that are not JSON

The [error object](/getting-started/errors/#error-object) covers every error raised by an endpoint. A few errors
are raised before the endpoint runs, by the HTTP framework, and come back as plain text with no `code`:

| Situation | Status | Body |
| --- | --- | --- |
| The JSON body is malformed or misses a required field | `400` | Text, for example ``Json deserialize error: missing field `launch_id` at line 1 column 2`` |
| A `POST` that expects JSON is sent without a body or without `Content-Type: application/json` | `400` | `Content type error` |
| A query parameter has the wrong type | `400` | Text starting with `Query deserialize error:` |
| A path parameter cannot be parsed, for example a funding job ID that is not a UUID | `404` | Text |
| The route does not exist, or the method is not served on it | `404` | Empty |
| The body is larger than the endpoint accepts | `413` | Text |

To handle them:

- Read the `Content-Type` of every error response before parsing it. When it is not `application/json`, fall back
  to the HTTP status and keep the text for your logs.
- Send `Content-Type: application/json` and a JSON body on every `POST` that takes JSON, even when every field is
  optional. Send `{}` rather than no body: for example, [Deploy a Shield](/reference/shield/#deploy-shield) refuses an
  empty request.

## Successful status, failed outcome

Some operations act on several wallets or chains and answer `200` even when part or all of the work failed. On
these, a `200` only means the request was processed. Read `ok` and the per-item results before you report success.

| Endpoint | What a `200` can hide |
| --- | --- |
| [Buy back the token](/reference/launch-trading/#buyback) | On Solana, `ok` is `false` when every buy failed. |
| [Nuke a launch](/reference/launch-trading/#nuke) | On EVM chains, `ok` stays `true` when every sale failed. Read `failed`. |
| [Sell dividends](/reference/launch-fees/#sell-dividends) | Some sales can fail while the call succeeds. |
| [Resume a Streamflow airdrop](/reference/launch-execution/#resume-streamflow-airdrop) | `ok` is `false` when any claim failed. |
| [Rescue MEV contracts](/reference/launch-execution/#rescue-mev-contracts) | A contract whose transfer failed is skipped; the call still answers `ok: true`. |
| [Collect referral fees](/reference/referrals/#collect-referral-fees) | Each chain has its own result under `results`; `ok` is `true` only when every chain succeeded. |
| [Swap funding to the quote token](/reference/launch-funding/#swap-to-quote) | On EVM chains, `ok` is `false` and `message` reads `Swapped <n> of <m> wallets` when some swaps failed. Read `swapped` and `failed`. |
| [Claim staking rewards](/reference/printr-staking/#claim-staking-rewards) | Each claim has its own result in `results`; the call fails only when every claim failed. |

Two calls can also stop halfway with an error after part of the work landed:

- [Swap funding to the quote token](/reference/launch-funding/#swap-to-quote) on Solana fails as a whole when one
  wallet fails, after other wallets may already have swapped.
- [Reclaim LP](/reference/liquidity/#reclaim-lp) on Solana sends up to three transactions in a row; a `422` can follow
  a partial withdrawal.

Read balances again before you retry either of them.

### Late confirmation

On Solana, the sell, nuke and transfer endpoints can confirm a request that had already been sent, instead of
running it again. They answer `200` with this body:

```json
{
  "ok": true,
  "landed": true,
  "request_id": "b7c1e0a4-6f0e-4a4e-9d6e-2a3f0c9b1d55",
  "tx_hashes": ["5h3xQ…"],
  "message": "landed, its records follow: do not send it again"
}
```

The transactions landed; the balances and [activity events](/reference/history/#list-launch-events) that record
them follow shortly. Treat it as a success and do not send the request again.

## Refusals sent as `500`

Several checks on Solana launches and wallets answer `500 internal_error` with a meaningful `message`, where a
`4xx` would be expected. They are deterministic: retrying gives the same answer.

| `message` | Raised by |
| --- | --- |
| `Token already launched` | Plan, funder and script changes after the launch |
| `Token not launched` | Trading and fee endpoints before the launch |
| `No launch method saved` | Launching without a saved plan |
| `Funding already running` | Funding the launch wallets twice |
| `Funder not found`, `Cannot remove the last funder` | Funder endpoints on Solana |
| `Wallet not found` | Updating a wallet |
| `Funding delay out of bounds` | Funding drafts |

The reference lists every one of them with its exact message. Before retrying a `500`, read `message`: if it
matches a documented refusal, fix the request instead.

> **Info:** The [retry strategy](/getting-started/errors/#retry-strategy) says to retry a `500` once. That still holds for
> messages you do not recognise; it is wasted work for the refusals listed here.

## Status codes that differ by chain

Solana and EVM chains are served by different code paths, and the same condition can come back with a different
status:

| Condition | Solana | EVM chains |
| --- | --- | --- |
| The launch has already happened | `500` | `400` |
| The launch has not happened yet | `500` | `400` or `404` |
| The launch has no saved plan | `404` or `500` | `400` |
| The amount is above the dev wallet's balance | `422` | `400` |
| The funder does not exist | `500` | `404` |
| Discarding a funding job that is running | `409` | `400` |

The messages can differ too, for example `Subs funding not completed` on Solana and `Holder funding not completed`
on EVM chains. Branch on the status class and `code`, and use the reference entry of each endpoint for the exact
pairs.

## Repeats that are not refused

Most money operations refuse a repeat while the first is running (`lane_pending` or a `409`). A few do not. Each
one is marked **Check before retrying** in its Requirements box:

- [Fund the launch wallets](/reference/launch-execution/#fund-launch-wallets) on EVM chains: a repeat can fund the
  wallets twice.
- [Nuke a launch](/reference/launch-trading/#nuke) on EVM chains: a repeat runs alongside the first one.
- [Start a session](/reference/generate-activity/#start-a-session) on EVM chains: a repeat starts a second session.
- [Buy back the token](/reference/launch-trading/#buyback): every call buys again.
- [Create a funding draft](/reference/funding/#create-a-funding-draft) on Solana: with `funder_pubkey` set to
  `"none"` or `"fresh"`, every call creates a new funder.
- [Update the launch plan](/reference/launches/#update-launch-plan): a wallet slot without a `key` gets a new wallet
  on every call.

> **Warning:** [Pay a quote](/reference/marketplace-orders/#pay-a-quote) keeps a quote locked after a payment whose outcome is
> uncertain. Every later attempt answers `409` with "a payment for this quote has already been sent and is waiting to
> be credited", even when nothing arrived. Do not loop on it: contact support with the quote ID.

## Stopping automations

Auto Buy, Auto Sell, Volume Bot and Sniper Guard sessions behave differently on Solana and EVM chains when you stop
them:

| Call | Solana | EVM chains |
| --- | --- | --- |
| Discard a session that is running | `409`: cancel it first | `200`, and **the session keeps running** |
| Cancel, pause or resume with an unknown `layer_id` or `mode` | `400` | `200`, nothing changes |

To stop a session on any chain, [cancel it](/reference/auto-sell/#cancel-auto-sell), read its
[status](/reference/auto-sell/#get-auto-sell-status) until it is no longer running, then discard it.

On EVM chains, [Start an Auto Sell session](/reference/auto-sell/#run-auto-sell) and its Auto Buy and Volume Bot
equivalents save the session as planned before the engine accepts it. When the engine refuses, the planned session
stays behind; discard it before you plan again. When a planned session already exists, its saved parameters win over
the request body.

## Fields the API ignores

These request fields are accepted without error but have no effect:

| Endpoint | Ignored fields |
| --- | --- |
| [Create a launch](/reference/launches/#create-launch) | `host`, `tracker`, `zaio`, `launch_platform` |
| Trading endpoints ([buyback](/reference/launch-trading/#buyback), [sell](/reference/launch-trading/#sell-dev-supply), [nuke](/reference/launch-trading/#nuke)…) | `fake_tip`, `fake_tip_pct`, `terminal`, `routing` |
| [Create a funding draft](/reference/funding/#create-a-funding-draft) on EVM chains | A `funder_pubkey` that is not a `0x` address: the default funder is used instead |
| [Run an activity plan](/reference/wallet-activity/#run-an-activity-plan) | `budgets` on any EVM chain other than the first one in `chains`: each EVM wallet only takes the budget of that first chain |
| [Plan an Auto Sell session](/reference/auto-sell/#plan-auto-sell) and its Auto Buy equivalent | The session-level `min_mcap` and `max_mcap`. Set market-cap bounds on each layer instead. |

## Unusual response shapes

| Endpoint | Shape |
| --- | --- |
| [Delete wallets](/reference/wallets/#delete-wallets) | On Solana, when no wallet matches, a bare JSON string: `"No matching wallets found"`. |
| [Remove watch wallets](/reference/wallets/#remove-watch-wallets) | `{ "removed": 2 }`, with no `ok` field. |
| [Retrieve the license](/reference/licenses/#retrieve-license), [Retrieve the Shield](/reference/shield/#retrieve-shield) | A `404` can also mean the read failed. Retry once before treating the resource as missing. |
| [Wallet](/reference/wallets/#object-wallet) PnL fields | On Solana, `pnl_native`, `pnl_usd` and `pnl_usd_total` read `0` for a loss. On EVM chains, `pnl_native` keeps its sign and `pnl_usd` always reads `0`. |

Amounts follow the [conventions](/getting-started/conventions/), with one gap: some totals are JSON numbers on
Solana and strings on EVM chains. Parse both.

## Chains

- **Monad** is no longer served. Chain-scoped routes answer `400` with `unknown chain_id: monad`. The value can
  still appear in older records and in some enums.
- **Quote tokens** are only served for Solana: [List quote tokens](/reference/launch-platforms/#list-quote-tokens)
  with any other `chain_id` answers an empty `404`.
- **Lesgo** launches are being withdrawn. Recent API builds no longer serve
  [Prepare a Lesgo config](/reference/launch-execution/#prepare-lesgo-config) and the other `/launch/sol/lesgo/*`
  routes.
- The [activity history](/reference/history/#list-events) `chain` filter accepts `sol`, `bsc`, `eth`, `base`,
  `robinhood` and `xlayer`. Any other value answers `400`.

## Access

- The X tracker (`/tracker/*`) and the [unscoped datafeed tokens](/reference/charts/#create-unscoped-token) are
  admin-only for now. Other accounts get `403 forbidden`.
- On a launch shared with you, every action other than a read needs two-factor authentication enabled on your own
  account. Without it, the API answers `403` with "acting on a shared launch needs two-factor authentication on your
  own account".
- Actions on shared launches can be challenged with the `launch.delegated` label. It does not appear in the list of
  [protected actions](/getting-started/two-factor-step-up/) and cannot be turned off. Answer it like any other
  challenge.

## Sessions

[Revoking a session](/reference/authentication/#revoke-session) takes effect at once on the server that handles the
call. Other servers can keep accepting the session's tokens for up to **30 seconds**. Do not rely on a revoked token
being refused immediately.

## Endpoints documented from the web client

The web client calls these endpoints, but they are not in the API source this reference was checked against. Their
reference entries are written from the web client alone: the requests are what it sends and the responses are what
it reads, and their errors are not documented.

| Endpoint | Note |
| --- | --- |
| [Create a realtime connection token](/reference/authentication/#create-realtime-token) | `GET /auth/ws-token` |
| [Cashback](/reference/referrals/#retrieve-cashback) and [Collect cashback](/reference/referrals/#collect-cashback) | `GET /license/cashback`, `/license/cashback-history`, `/license/cashback-series` and `POST /license/collect-cashback` |
| [List quotes](/reference/marketplace-orders/#list-quotes) | `GET /marketplace/quotes` currently answers an empty `404`. |
