> For the complete documentation index, see [llms.txt](https://docs.lighter.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lighter.xyz/developers/going-to-production/troubleshooting.md).

# Troubleshooting

Symptoms, causes and fixes for the most common integration problems.

Error codes and their names are listed in [Data Structures, Constants and Errors](/developers/reference/data-structures-constants-and-errors.md#error-codes). This page covers what usually causes them.

{% hint style="info" %}
For the current binary options discovery methods and response models, use [lighter-sdk 1.1.8](https://pypi.org/project/lighter-sdk/1.1.8/) or newer, or [lighter-go v1.0.12](https://github.com/elliottech/lighter-go/releases/tag/v1.0.12) or newer. Python 1.1.8 also fixes the `boPnl` authorization header. The standard create, modify and cancel order flow is unchanged; discover binary options market IDs through `events`.

The shared-library signer uses signed 64-bit market indices (`int64`). If you call it directly from C/C++ or a custom FFI binding, use a `.h` file and bindings that match your signer library. Update declarations that still use `int cMarketIndex` to `long long int cMarketIndex`, as shown in the [current signer header](https://github.com/elliottech/lighter-python/blob/v1.1.8/lighter/signers/lighter-signer-linux-amd64.h#L158).

See the [Python binary options examples](https://github.com/elliottech/lighter-python/tree/v1.1.8/examples/binary-options), especially [create\_order\_from\_event.py](https://github.com/elliottech/lighter-python/blob/v1.1.8/examples/binary-options/create_order_from_event.py), for market discovery through `events` followed by `create_order`.
{% endhint %}

### `sendTx` returned 200 but my order isn't there

`200` means the API accepted the transaction. The sequencer can still reject it, for example because of a price outside the allowed band, a taker order that can't fill at your worst price, or insufficient margin for a taker order. Check `account_tx/{account}` on WebSocket or `GET /api/v1/tx?by=hash&value=<tx_hash>`.

### `invalid nonce` (21104)

* Two processes are using the same API key concurrently. Use one key per process, or serialize.
* A previous tx failed in the sequencer **without** consuming its nonce (e.g. `ExpiredAt` passed, not enough margin for a resting order), so the later nonces you already sent are now one step ahead and fail too. Refetch `nextNonce` and re-sign. See [When a rejected transaction consumes its nonce](/developers/getting-started/core-concepts.md#when-a-rejected-transaction-consumes-its-nonce).
* Batch nonces must be consecutive (21105).

### `invalid PublicKey, please run changePubKey` (21108) / key check fails

The key at that `apiKeyIndex` isn't registered for that `accountIndex`, or it was replaced by another app using the same index. Register it again ([Create accounts programmatically](/developers/integration-guides/create-accounts-programmatically.md)).

### Signature rejected / wrong chain

The `chainId` in `CreateClient` must be `304` for mainnet and `300` for testnet. See [Environments & endpoints](/developers/getting-started/environments.md).

### Order size or price is off by powers of ten

You mixed up decimals. `base_amount = size × 10^size_decimals`, `price = price × 10^price_decimals`, taken from `orderBookDetails` for **that** perps or spot market, or from [events](https://docs.lighter.xyz/api/binary-options) for binary options. If you use `lighter-ts`, also watch the display/real `multiplier` (see [Market data](/developers/integration-guides/market-data.md#using-lighter-ts)).

### Order rejected as too small

Below `min_base_amount` or `min_quote_amount` (the larger applies). For binary options, the minimum quote check uses `P × size` for both buy and sell orders, where `P` is the Up price. A Down order can fail this check even when its `(1 − P) × size` cost exceeds the minimum. See [Binary options order rules](/developers/binary-options/trading-and-fees.md#order-rules).

### Binary options create or modify rejected

| Code    | Check                                                                                                                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `21631` | The transaction's block time must fall within the market's `start_timestamp`–`end_timestamp`. Refresh [events](https://docs.lighter.xyz/api/binary-options) and select a market whose trading window is open |
| `21632` | Use a price below `settlement_cap`; for Up/Down this means integer ticks `1`–`99`, not `100`                                                                                                                 |
| `21638` | The operator has frozen the order book; check `is_frozen` before retrying                                                                                                                                    |

These checks apply to both `CreateOrder` and `ModifyOrder`. See [Binary options: Trading and fees](/developers/binary-options/trading-and-fees.md#errors).

### Integrator fee rejected

The client is on Standard, the fee exceeds the approved max, the approval expired, or the client already has 4 partners. See [Partner Attribution](/developers/integration-guides/partner-attribution.md).

### HTTP 429 / 405

Rate limited. Back off, authenticate requests, reduce polling (use WebSocket), or change tier. See [Rate Limits](/developers/reference/rate-limits.md).

### WebSocket disconnects

No frame within 2 minutes, too many subscriptions, reading too slowly, or a server deployment. Send pings every \~60 s and reconnect automatically.

### `account not found` (21100) after a deposit

Deposits take a few minutes to credit (CCTP: \~15–20 min). Poll `accountsByL1Address`, or check UDA status.

### WASM: `argument N is undefined` / `expects N args`

Every positional argument is required. Pass `0` for unused ones. Check the order in [WASM signer functions](/developers/reference/wasm-signer.md).

## Still stuck?

Open a ticket in `#support` on [Discord](https://discord.gg/lighterxyz) with the `tx_hash`, account index, API key index and the full response.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.lighter.xyz/developers/going-to-production/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.