> ## Documentation Index
> Fetch the complete documentation index at: https://www.velora.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API troubleshooting guide

> Common failure modes across the Velora Delta and Market APIs: symptom, root cause, and fix.

export const orderId_0 = undefined

Each table covers a single endpoint and is updated from support tickets at each release. Jump straight to the endpoint you're calling.

<Tip>
  Building error-handling logic or LLM tools? Read [`/resources/errors.json`](/docs/resources/errors.json) — it mirrors every row on this page in machine-readable form, with `endpoint`, `status`, `match`, `cause`, `fix`, and `docs` fields per error.
</Tip>

## Delta V2 API

### GET /v2/delta/prices

| Symptom | Root cause | Fix |
| - | - | - |
| 400 `No route` for a same-chain pair | Token pair has no liquidity, or `srcDecimals` / `destDecimals` are wrong | Re-check decimals against the token contract; try `mode=ALL` on [GET /v2/quote](/docs/api-reference/delta/quote) to see whether Market can route it |
| 400 `No route` for a crosschain pair | `destChainId` lane not supported by any active bridge for this token | Call [GET /v2/delta/prices/bridge-routes](/docs/api-reference/delta/bridge-routes) to see which lanes + tokens are supported |
| `route.bridge` is `null` on a crosschain quote | `srcToken` and `destToken` happen to be the same address on different chains and the bridge collapsed | Compare `route.origin.input.token.chainId` vs `route.destination.output.token.chainId` directly; don't infer crosschain from `bridge !== null` alone |
| `alternatives` is empty | Same-chain quotes never return alternatives — only crosschain | Use `route` directly for same-chain; check `alternatives.length > 0` before showing a bridge picker |
| `partner.feePercent` higher than expected | Registered partner fee + `partnerFeeBps` override compounded | Set `partnerFeeBps=0` (or omit) to use the registered fee only; passing both stacks them |
| 400 `Token not supported` | One of `srcToken` / `destToken` isn't whitelisted on `chainId` | Call [GET /v2/delta/prices/is-token-supported](/docs/api-reference/delta/is-token-supported) before quoting |

<Note>Updated from support tickets at each release. Last updated: 2026-05-27.</Note>

### POST /v2/delta/orders/build

| Symptom | Root cause | Fix |
| - | - | - |
| 400 `route` validation failed | `route` object was mutated, re-stringified, or had numeric fields cast to numbers (they're strings) | Pass `route` from [GET /v2/delta/prices](/docs/api-reference/delta/prices) **verbatim** — don't normalize, sort, or re-encode amounts |
| 400 missing `deadline` | `deadline` is required on every Delta order; the build call rejects when it's absent | Pass `deadline` as unix seconds (e.g. `Math.floor(Date.now() / 1000) + 3600`); past it the order is unfillable |
| 400 `InvalidTWAPParams` / `InvalidTWAPBuyParams` | TWAP / TWAPBuy without `interval`, `numSlices`, and a totals field | Provide all four: `interval` (seconds, ≥ 60), `numSlices` (≥ 2), `totalSrcAmount` (TWAP), or `totalDestAmount` + `maxSrcAmount` (TWAPBuy) |
| 400 `InvalidTWAPSrcAmount` / `InvalidTWAPBuyDestAmount` | Slice amount in `route.origin` doesn't equal `floor(total / numSlices)` | Re-quote per slice with `amount = floor(total / numSlices)` and pass the totals separately; non-divisible remainders are intentional and you can't ship slice×n |
| 400 `InvalidExternalOrderParams` | `orderType: ExternalOrder` without `handler` and `data` | Encode handler-specific bytes into `data` and pass the on-chain handler address as `handler` |
| 400 `InvalidProductiveOrderParams` | `orderType: ProductiveOrder` without `strategy` | Pass the on-chain strategy address as `strategy` |
| `slippage` results in much worse fills than expected | Slippage is in **basis points**, not percent: `100` = 1.00%, not 100% | Convert mental percent to bps: 0.5% → `50`, 1% → `100`, 5% → `500` (max `10_000` = 100%) |

<Note>Updated from support tickets at each release. Last updated: 2026-06-09.</Note>

### POST /v2/delta/orders/build/cancellation

| Symptom | Root cause | Fix |
| - | - | - |
| 400 `Orders are not found` | At least one `orderIds` value is unknown or does not belong to a Delta V2 order | Refresh the user's order list with [GET /v2/delta/orders](/docs/api-reference/delta/orders-list) and build from returned `id` values only |
| 400 `All orders must belong to the same user and chain` | The batch mixes orders from different owners or source chains | Group orders by owner and source chain; call this endpoint once per group |
| 400 `All orders are already finalized` | Every requested order is terminal or already resolving cancellation | Skip orders that are `COMPLETED`, `FAILED`, `EXPIRED`, `CANCELLED`, `REFUNDED`, or already `CANCELLING` |
| Signature later rejected by `POST /v2/delta/orders/cancel` | The client signed a reconstructed payload instead of the returned `toSign` object | Sign `toSign.domain`, `toSign.types`, and `toSign.value` exactly, then send the same `orderIds` to cancel |
| 400 `orderIds.length > 100` | Tried to build one cancellation payload for too many orders | Chunk into batches of 100 or fewer |

<Note>Updated from support tickets at each release. Last updated: 2026-06-25.</Note>

### POST /v2/delta/orders

| Symptom | Root cause | Fix |
| - | - | - |
| 400 `Invalid signature` | Signed payload doesn't match `order` byte-for-byte | Sign `toSign` from `POST /v2/delta/orders/build` exactly; pass `order: toSign.value` to submit (not the whole `toSign` object) |
| 400 `Order expired` | Long pause between build and submit; `deadline` already passed when relayer validated | Rebuild on submit-time, or pass a longer `deadline` (seconds since epoch) at build |
| 400 `InsufficientAllowance` | User approved the wrong spender — usually the Augustus router instead of the Delta contract | Approve `route.spender` (returned by `GET /v2/delta/prices`) — the Delta contract, not Augustus |
| 400 `InsufficientBalance` | Source-token balance dropped between price and submit | Re-quote and rebuild; show the user a fresh balance before signing |
| 200 OK then stuck at `PENDING` | No agent bid the auction (size, pair, or chain) within the window | Poll [GET /v2/delta/orders/{orderId_0}](/docs/api-reference/delta/orders-get-by-id); build a cancellation payload with [POST /v2/delta/orders/build/cancellation](/docs/api-reference/delta/orders-build-cancellation), then cancel and re-quote if past your SLA |
| Order transitions to `SUSPENDED` | Allowance was revoked or balance moved post-submission | Re-approve and the relayer will pick the order back up |
| Native-source order stuck at `AWAITING_SIGNATURE` | Submitted with `signature: "0x"` but the `depositNativeAndPreSign` transaction never landed, or deposited less than `srcAmount` | Send `depositNativeAndPreSign(orderHash)` to the Delta contract with `value` equal to the order's `srcAmount`; see [Native ETH (dETH)](/docs/delta/native-eth) |
| Native-source order `SUSPENDED` after being active | The user's dETH balance dropped below `srcAmount` (unwrapped, transferred, or spent by another native order) | Top the balance back up with `depositNative`, or cancel and re-quote |
| 400 `deadline must allow enough time for all slices to execute` | TWAP `deadline` is less than `numSlices × interval` seconds away | Push the deadline past `now + numSlices × interval`, or use fewer slices / a shorter interval |
| 400 `totalSrcAmount must be >= numSlices` (also `totalDestAmount`, `maxSrcAmount`) | TWAP total is smaller than the slice count, so a slice would round down to 0 wei | Raise the total or lower `numSlices` so every slice carries at least 1 wei |

<Note>Updated from support tickets at each release. Last updated: 2026-06-12.</Note>

### POST /v2/delta/orders/cancel

| Symptom | Root cause | Fix |
| - | - | - |
| 400 `Invalid signature` | Cancellation EIP-712 typed data assembled wrong (wrong chainId or wrong domain) | Sign the `toSign` payload from [POST /v2/delta/orders/build/cancellation](/docs/api-reference/delta/orders-build-cancellation); the SDK's `signCancelDeltaOrderRequest` handles this for you |
| 400 `Order already settled` | One or more `orderIds` are already post-settlement or terminal (`COMPLETED`, `REFUNDING`, `REFUNDED`, `FAILED`, `EXPIRED`, `CANCELLED`) | Pre-filter `orderIds` to those with status in `PENDING` / `AWAITING_SIGNATURE` / `ACTIVE` / `SUSPENDED` / `EXECUTING` |
| 200 OK but order doesn't move to `CANCELLING` | An auction had already started for that order — cancellation queues but won't kill an in-flight fill | Wait one polling interval; the order moves to `CANCELLED` once the relayer confirms |
| 400 `orderIds.length > 100` | Tried to batch-cancel too many in one call | Chunk into batches of ≤ 100 |

<Note>Updated from support tickets at each release. Last updated: 2026-06-15.</Note>

## Market API

### GET /prices

| Symptom | Root cause | Fix |
| - | - | - |
| 400 `Invalid srcToken` or `Invalid destToken` | Native ETH sent as `0x0` or lowercase `0xeee...e` | Use the mixed-case placeholder `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` |
| 422 `Unsupported chain` | `network` not in the supported-chain list for the current API host | Hit `GET /chains` to confirm the live list; see [Chains & contracts](/docs/resources/chains-and-contracts) |
| `priceRoute.maxImpactReached: true` | Price impact exceeds the configured ceiling for this route | Reduce trade size, split into hops, or pass an explicit higher `maxImpact` if your product accepts the risk |
| Stale `priceRoute` rejected by `POST /transactions/:chainId` | More than \~30s elapsed between quote and tx-build, route became invalid | Re-quote and pass the fresh `priceRoute` verbatim; never cache across user gestures |
| 429 from the gateway | Free-tier rate limit hit, or your Pro plan quota exceeded | See [Pro API accounts](/docs/overview/pro-api-accounts) to lift rate limits, or back off and retry |

<Note>Updated from support tickets at each release. Last updated: 2026-05-15.</Note>

### POST /transactions/:chainId

| Symptom | Root cause | Fix |
| - | - | - |
| 400 `Invalid priceRoute` or `Stale priceRoute` | `priceRoute` modified between quote and tx-build, or older than \~30s | Pass the `priceRoute` block from `GET /prices` verbatim; re-quote if more than \~30s elapsed |
| Calldata reverts on-chain with `INSUFFICIENT_OUTPUT` | Slippage tolerance too tight for current market depth | Increase `slippage` (in bps) on the rebuild, or surface a higher tolerance to the user before retrying |
| Calldata reverts with `TransferHelper: TRANSFER_FROM_FAILED` | ERC-20 allowance to the v6.2 router insufficient (or pointed at the legacy v5 router) | Approve the Augustus v6.2 router address — see [Chains & contracts](/docs/resources/chains-and-contracts); migrating off v5 → [Augustus v5 → v6.2](/docs/resources/migrations/augustus-v5-to-v6-2) |
| `txData` gas estimate fails on the user's RPC | RPC gas estimation can't simulate the exact block conditions | Use the `gas` field returned in the response as a baseline + 15–25% headroom |
| Calldata builds for the wrong chain | `network` path parameter mismatched against the `priceRoute.network` | Always derive `:network` from `priceRoute.network`, not from a client-side variable |
| 422 `Partner not allowed` | Your partner tier doesn't permit the requested fee/surplus configuration | Drop the disallowed param, or [upgrade to a Pro API account](/docs/overview/pro-api-accounts) |

<Note>Updated from support tickets at each release. Last updated: 2026-05-15.</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.