> For the complete documentation index, see [llms.txt](https://docs.anchored.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.anchored.finance/trading-api/reference/troubleshooting.md). # Troubleshooting Use this guide when an API request fails, a transaction reverts, or an order/cash operation appears stuck. ## First Triage Start with the layer where the failure appears: 1. If API `code` is not `200`, fix request auth, scope, or parameters first. 2. If API succeeds but no transaction is submitted, inspect the calldata response and wallet client. 3. If the transaction is submitted but reverts, debug allowance, balance, deadline, chain, and router target. 4. If the transaction succeeds but the API cannot find it, record `txHash` or wait for indexer backfill. 5. If mapping exists but state is not final, poll order or cash detail endpoints. ## API Auth Fails Symptoms: * HTTP `400` with `code: 401` * `Unauthorized` * Signature, nonce, timestamp, IP, or permission errors All of these return the **same** `401 Unauthorized` — the response body does **not** say which one failed. Rule them out one by one; for a new integration, check the IP whitelist and timestamp first. | Check | Fix | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | API key invalid, inactive, or expired | Confirm the key exists, is `active`, and `expires_at` is unset or future | | Empty or mismatched IP whitelist | Add your egress IP ([headers-and-permissions.md](/trading-api/authentication/headers-and-permissions.md)); an empty whitelist rejects everything | | `x-api-ts` outside 45-second window | Use current UTC milliseconds | | Reused `x-api-nonce` | Use a unique UUID per request | | Wrong HMAC URI | Authenticate `/api/v1/...`, not the full URL | | Literal `\n` in signed payload | Join the 5 lines with **real newlines**, not the two-character `\n` (a common shell bug — see [signature.md](/trading-api/authentication/signature.md)) | | Query order mismatch | Sort query params by name before HMAC authentication | | Body mismatch | Sign the exact JSON string sent | | Missing scope | Confirm `chainId + productType + access` permission | ## Order Rejected Before Calldata Is Built The API rejects some orders up front (non-`200`, before any transaction), so a bad order never reaches the chain. These apply to both `/calldata` and `/send`: | Message | Cause | Fix | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | `market order is only supported during the regular trading session (current: )` | Market order (incl. deferred market sell) placed outside the regular US session (pre-market / after-hours / overnight / closed) | Wait for the regular session, or use a **limit** order | | `deferred sell is not allowed for this address` / `... is restricted ...` | Address not whitelisted (`allowed && !restricted`) for deferred sell | Have the deferred-sell manager configure the address | | `timeInForce only supports DAY ...` | Limit order with non-`DAY` TIF | Use `timeInForce: "DAY"` | ## Calldata Builds But Chain Transaction Reverts Common causes: | Symptom | Likely cause | Fix | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | Deposit tx reverts | Insufficient ERC-20 allowance | Check `walletAllowance`; approve spender | | Deposit tx reverts | Wallet token balance too low | Check `walletBalance` | | Order tx reverts | Plain buy has insufficient `mUsdBalance` | Deposit first, use `/orders/with-deposit/*` when eligible, or reduce `notional` | | Sell tx reverts | Plain sell has insufficient `exchangeBalance`, or order-with-deposit sell lacks stock allowance/balance | Approve stock, use `/orders/with-deposit/*`, or reduce quantity | | Cancel tx reverts | Order not open or already canceling | Query `/orders/{orderId}` first | | Tx reverts out-of-gas (`gasUsed == gasLimit`) | Default `estimateGas` is too low on some chains (e.g. Monad) for router calls | Self-submit: add a gas buffer (`estimateGas × 1.5–2`). One Click: pass a sufficient `gasLimit` | | Deadline error | `deadline` expired | Use a future Unix seconds value | | Wrong chain | Wallet on different chain than `x-api-chain-id` | Switch wallet network | ## Deposit Not Credited Yet A mined deposit transaction still needs API mapping and, for queued deposits, final cash settlement before `mUsdBalance` updates. If the transaction succeeded: 1. Confirm `POST /api/v1/cash/deposits/tx` was called with the correct `txHash`. 2. Poll `GET /api/v1/cash/deposits/{operationId}`. 3. Check `operationStatus`. 4. Refresh `GET /api/v1/users/{userId}/balance`. Queued deposits can remain `processing` while final cash settlement is still pending. ## Withdrawal Not Paid Out Yet Withdrawals can be instant or queued. If queued: 1. `mUSD` is deducted first. 2. Final cash settlement completes later. 3. Cashier transfers tokens to the user when settlement completes. Poll: ``` GET /api/v1/cash/withdrawals/{operationId} ``` Do not treat `processing` as failed unless the operation has an explicit failure status or support confirms an issue. ## Order Tx Mined But No Order ID This usually means the indexer has not backfilled the mapping yet. Check: ``` GET /api/v1/orders/tx/{txHash} ``` If missing: 1. Confirm the tx was sent to the returned `toAddress`. 2. Confirm the tx succeeded on the same chain as `x-api-chain-id`. 3. Confirm `POST /api/v1/orders/tx` was called by the same API key. 4. Wait for indexer backfill and retry. ## Order Open Too Long For limit orders, open state can be normal. Practical lifecycle rules depend on `timeInForce` and backend execution. > Production limit orders currently only accept `DAY`; other `timeInForce` values will make the order transaction revert. For market orders, long open time usually means one of: * Execution result not yet received. * Final order result has not settled on-chain. * Indexer/API has not refreshed status. Use: ``` GET /api/v1/orders/{orderId} ``` Then inspect `openOrder.status` and history fields. ## One Click Send Fails Check: | Check | Fix | | ---------------------------------- | ---------------------------------------------------- | | `/1ct/status` is not `enable` | Run prepare/sign/enable flow | | API key has no bound `userAddress` | Configure API key user binding | | Signer mismatch | EIP-712 signer must equal `signPayload.message.user` | | Expired deadline | Prepare and sign a fresh payload | | Deposit send fails | Bound user must approve cash token spender | ## Escalation Data When escalating to backend/support, include: * Environment base URL * `x-api-chain-id` * `x-api-p` * API response `code`, `errMsg`, `uuid`, `t` * `txHash` * `orderId` or `operationId` * Wallet address / `userId` * Request path and body (without API secret)