{
  "_meta": {
    "description": "Machine-readable mirror of the Velora API troubleshooting tables. Each row maps a documented symptom on a specific endpoint to its root cause, fix, and the human-readable docs anchor.",
    "source": "https://velora.xyz/docs/api-reference/troubleshooting",
    "lastUpdated": "2026-06-15",
    "note": "Documented examples — not an exhaustive enumeration of every possible error string. Updated from support tickets at each release."
  },
  "errors": [
    {
      "endpoint": "GET /prices",
      "status": 400,
      "match": "Invalid srcToken or Invalid destToken",
      "cause": "Native ETH sent as 0x0 or lowercase 0xeee...e.",
      "fix": "Use the mixed-case placeholder 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE.",
      "docs": "/api-reference/troubleshooting#get-prices"
    },
    {
      "endpoint": "GET /prices",
      "status": 422,
      "match": "Unsupported chain",
      "cause": "network not in the supported-chain list for the current API host.",
      "fix": "Hit GET /chains to confirm the live list; see /resources/chains-and-contracts.",
      "docs": "/api-reference/troubleshooting#get-prices"
    },
    {
      "endpoint": "GET /prices",
      "status": 200,
      "match": "priceRoute.maxImpactReached: true",
      "cause": "Price impact exceeds the configured ceiling for this route.",
      "fix": "Reduce trade size, split into hops, or pass an explicit higher maxImpact if your product accepts the risk.",
      "docs": "/api-reference/troubleshooting#get-prices"
    },
    {
      "endpoint": "GET /prices",
      "status": 400,
      "match": "Stale priceRoute",
      "cause": "More than ~30s elapsed between quote and tx-build; route became invalid.",
      "fix": "Re-quote and pass the fresh priceRoute verbatim; never cache across user gestures.",
      "docs": "/api-reference/troubleshooting#get-prices"
    },
    {
      "endpoint": "GET /prices",
      "status": 429,
      "match": "Too Many Requests",
      "cause": "Free-tier rate limit hit, or Pro plan quota exceeded.",
      "fix": "Upgrade to a Pro API account (see /overview/pro-api-accounts) to lift limits, or back off and retry.",
      "docs": "/api-reference/troubleshooting#get-prices"
    },
    {
      "endpoint": "POST /transactions/:chainId",
      "status": 400,
      "match": "Invalid priceRoute or Stale priceRoute",
      "cause": "priceRoute modified between quote and tx-build, or older than ~30s.",
      "fix": "Pass the priceRoute block from GET /prices verbatim; re-quote if more than ~30s elapsed.",
      "docs": "/api-reference/troubleshooting#post-transactions-chainid"
    },
    {
      "endpoint": "POST /transactions/:chainId",
      "status": null,
      "match": "INSUFFICIENT_OUTPUT (on-chain revert)",
      "cause": "Slippage tolerance too tight for current market depth.",
      "fix": "Increase slippage (in bps) on the rebuild, or surface a higher tolerance to the user before retrying.",
      "docs": "/api-reference/troubleshooting#post-transactions-chainid"
    },
    {
      "endpoint": "POST /transactions/:chainId",
      "status": null,
      "match": "TransferHelper: TRANSFER_FROM_FAILED (on-chain revert)",
      "cause": "ERC-20 allowance to the v6.2 router insufficient, or allowance pointed at the legacy v5 router.",
      "fix": "Approve the Augustus v6.2 router address — see /resources/chains-and-contracts; if migrating off v5, see /resources/migrations/augustus-v5-to-v6-2.",
      "docs": "/api-reference/troubleshooting#post-transactions-chainid"
    },
    {
      "endpoint": "POST /transactions/:chainId",
      "status": null,
      "match": "RPC gas estimate fails",
      "cause": "RPC gas estimation can't simulate the exact block conditions.",
      "fix": "Use the gas field returned in the response as a baseline + 15-25% headroom.",
      "docs": "/api-reference/troubleshooting#post-transactions-chainid"
    },
    {
      "endpoint": "POST /transactions/:chainId",
      "status": null,
      "match": "Calldata builds for the wrong chain",
      "cause": "network path parameter mismatched against priceRoute.network.",
      "fix": "Always derive :network from priceRoute.network, not from a client-side variable.",
      "docs": "/api-reference/troubleshooting#post-transactions-chainid"
    },
    {
      "endpoint": "POST /transactions/:chainId",
      "status": 422,
      "match": "Partner not allowed",
      "cause": "Your partner tier doesn't permit the requested fee/surplus configuration.",
      "fix": "Drop the disallowed param, or contact partnerships to upgrade the tier.",
      "docs": "/api-reference/troubleshooting#post-transactions-chainid"
    },
    {
      "endpoint": "GET /v2/quote",
      "status": 400,
      "match": "Invalid srcToken",
      "cause": "Native ETH sent as 0x0 or lowercase 0xeee...e.",
      "fix": "Use the mixed-case placeholder 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE.",
      "docs": "/api-reference/troubleshooting#get-quote"
    },
    {
      "endpoint": "GET /v2/quote",
      "status": 200,
      "match": "Response has market instead of delta",
      "cause": "mode=ALL and Market won the routing decision.",
      "fix": "Force mode=DELTA if Delta is required, or branch on response.delta vs response.market. See /integrate/trading-modes.",
      "docs": "/api-reference/troubleshooting#get-quote"
    },
    {
      "endpoint": "GET /v2/quote",
      "status": 400,
      "match": "Slippage required",
      "cause": "slippage omitted on a Delta quote.",
      "fix": "Pass slippage in basis points (e.g. 100 = 1%).",
      "docs": "/api-reference/troubleshooting#get-quote"
    },
    {
      "endpoint": "GET /v2/quote",
      "status": 422,
      "match": "Unsupported chain",
      "cause": "chainId is supported by Market but Delta hasn't shipped on that chain yet.",
      "fix": "Check GET /chains for the Delta-enabled subset; see /resources/chains-and-contracts.",
      "docs": "/api-reference/troubleshooting#get-quote"
    },
    {
      "endpoint": "GET /v2/quote",
      "status": 200,
      "match": "delta.partiallyFillable: false (unexpected)",
      "cause": "The pair / size combination doesn't have partial-fill liquidity from solvers.",
      "fix": "Reduce size, or design the UX around all-or-nothing fills for this pair.",
      "docs": "/api-reference/troubleshooting#get-quote"
    },
    {
      "endpoint": "GET /v2/quote",
      "status": 400,
      "match": "Invalid price (on subsequent /orders/build)",
      "cause": "delta block mutated between calls (recomputed amounts, decoded/re-encoded).",
      "fix": "Pass the delta object verbatim as price; hmac unchanged from the quote response.",
      "docs": "/api-reference/troubleshooting#get-quote"
    },
    {
      "endpoint": "POST /v2/delta/orders/build",
      "status": 400,
      "match": "Invalid price",
      "cause": "The delta block from GET /v2/quote was mutated, re-encoded, or re-stringified before submit.",
      "fix": "Pass the delta object verbatim as price. Don't run it through JSON normalizers, sorters, or schema validators.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-build"
    },
    {
      "endpoint": "POST /v2/delta/orders/build",
      "status": 400,
      "match": "Invalid hmac",
      "cause": "The hmac from the quote response was dropped, modified, or paired with a different delta.",
      "fix": "Always send the hmac paired with the exact delta returned from the same quote response.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-build"
    },
    {
      "endpoint": "POST /v2/delta/orders/build",
      "status": null,
      "match": "EIP-712 signature rejected",
      "cause": "Wallet signed against a different chain id, verifying contract, or version.",
      "fix": "Verify domain.chainId, domain.verifyingContract, and domain.name/version match what POST /v2/delta/orders/build returned.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-build"
    },
    {
      "endpoint": "POST /v2/delta/orders/build",
      "status": null,
      "match": "Approval reverts before signing",
      "cause": "Token approval granted to the Augustus router instead of the Delta contract.",
      "fix": "Approve the Delta contract as spender — it's the spender on Delta flows, not Augustus. See /resources/chains-and-contracts.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-build"
    },
    {
      "endpoint": "POST /v2/delta/orders/build",
      "status": null,
      "match": "Build succeeds but downstream /v2/delta/orders returns expired",
      "cause": "Long delay between build and signature (user wandered off, app backgrounded).",
      "fix": "Re-quote and rebuild when the user returns; treat order-server expiry as a hard ceiling, surface a countdown in your UI.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-build"
    },
    {
      "endpoint": "POST /v2/delta/orders/build",
      "status": 400,
      "match": "Permit / Permit2 required",
      "cause": "The token requires Permit or Permit2 and the build request didn't include the payload.",
      "fix": "Detect Permit/Permit2 capability up front and include the payload in the build request.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-build"
    },
    {
      "endpoint": "POST /v2/delta/orders/build/cancellation",
      "status": 400,
      "match": "Orders are not found",
      "cause": "At least one orderIds value is unknown or does not belong to a Delta V2 order.",
      "fix": "Refresh the user's order list with GET /v2/delta/orders and build from returned id values only.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-build-cancellation"
    },
    {
      "endpoint": "POST /v2/delta/orders/build/cancellation",
      "status": 400,
      "match": "All orders must belong to the same user and chain",
      "cause": "The batch mixes orders from different owners or source chains.",
      "fix": "Group orders by owner and source chain; call this endpoint once per group.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-build-cancellation"
    },
    {
      "endpoint": "POST /v2/delta/orders/build/cancellation",
      "status": 400,
      "match": "All orders are already finalized",
      "cause": "Every requested order is terminal or already resolving cancellation.",
      "fix": "Skip orders that are COMPLETED, FAILED, EXPIRED, CANCELLED, REFUNDED, or already CANCELLING.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-build-cancellation"
    },
    {
      "endpoint": "POST /v2/delta/orders/build/cancellation",
      "status": null,
      "match": "Signature later rejected by POST /v2/delta/orders/cancel",
      "cause": "The client signed a reconstructed payload instead of the returned toSign object.",
      "fix": "Sign toSign.domain, toSign.types, and toSign.value exactly, then send the same orderIds to cancel.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-build-cancellation"
    },
    {
      "endpoint": "POST /v2/delta/orders/build/cancellation",
      "status": 400,
      "match": "orderIds.length > 100",
      "cause": "Tried to build one cancellation payload for too many orders.",
      "fix": "Chunk into batches of 100 or fewer.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-build-cancellation"
    },
    {
      "endpoint": "POST /v2/delta/orders",
      "status": 400,
      "match": "Invalid signature",
      "cause": "Signed payload doesn't match the order field byte-for-byte.",
      "fix": "Sign the exact order returned by POST /v2/delta/orders/build. Don't re-sort, re-stringify, or re-encode.",
      "docs": "/api-reference/troubleshooting#post-delta-orders"
    },
    {
      "endpoint": "POST /v2/delta/orders",
      "status": 400,
      "match": "Order expired immediately",
      "cause": "More than ~30s elapsed between build and submit.",
      "fix": "Submit the signed order within the validity window; if the user pauses, re-quote and rebuild.",
      "docs": "/api-reference/troubleshooting#post-delta-orders"
    },
    {
      "endpoint": "POST /v2/delta/orders",
      "status": 200,
      "match": "Order stays at pending indefinitely",
      "cause": "Solver auction returned no fill (size, pair, or chain conditions).",
      "fix": "Poll GET /v2/delta/orders/:id; if still pending past your SLA, cancel and re-quote.",
      "docs": "/api-reference/troubleshooting#post-delta-orders"
    },
    {
      "endpoint": "POST /v2/delta/orders",
      "status": 200,
      "match": "Order transitions to failed post-acceptance",
      "cause": "Allowance revoked, balance moved, or token-approval points at the wrong spender.",
      "fix": "Confirm allowance to the Delta contract spender persists for the order's full lifecycle. See /resources/chains-and-contracts.",
      "docs": "/api-reference/troubleshooting#post-delta-orders"
    },
    {
      "endpoint": "POST /v2/delta/orders",
      "status": 200,
      "match": "partialFill order settles partial then stalls",
      "cause": "Solver network couldn't source the remainder at the signed price.",
      "fix": "Decide whether to cancel and re-quote the remainder, or wait for the full validity window.",
      "docs": "/api-reference/troubleshooting#post-delta-orders"
    },
    {
      "endpoint": "POST /v2/delta/orders",
      "status": 200,
      "match": "No order id returned",
      "cause": "Client treated empty response as success; gateway response was actually a 5xx.",
      "fix": "Always check status and presence of id; retry on 5xx with idempotent re-submission of the same signed payload.",
      "docs": "/api-reference/troubleshooting#post-delta-orders"
    },
    {
      "endpoint": "POST /v2/delta/orders/cancel",
      "status": 400,
      "match": "Invalid signature",
      "cause": "Cancellation EIP-712 typed data assembled wrong (wrong chainId or wrong domain).",
      "fix": "Sign the toSign payload from POST /v2/delta/orders/build/cancellation; the SDK's signCancelDeltaOrderRequest handles this for you.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-cancel"
    },
    {
      "endpoint": "POST /v2/delta/orders/cancel",
      "status": 400,
      "match": "Order already settled",
      "cause": "One or more orderIds are already post-settlement or terminal: COMPLETED, REFUNDING, REFUNDED, FAILED, EXPIRED, or CANCELLED.",
      "fix": "Pre-filter orderIds to PENDING, AWAITING_SIGNATURE, ACTIVE, SUSPENDED, or EXECUTING.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-cancel"
    },
    {
      "endpoint": "POST /v2/delta/orders/cancel",
      "status": 200,
      "match": "OK but order doesn't move to CANCELLING",
      "cause": "An auction had already started for that order; cancellation queues but won't kill an in-flight fill.",
      "fix": "Wait one polling interval; the order moves to CANCELLED once the relayer confirms.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-cancel"
    },
    {
      "endpoint": "POST /v2/delta/orders/cancel",
      "status": 400,
      "match": "orderIds.length > 100",
      "cause": "Tried to batch-cancel too many orders in one call.",
      "fix": "Chunk into batches of <= 100.",
      "docs": "/api-reference/troubleshooting#post-delta-orders-cancel"
    }
  ]
}