Errors | VeTrade Developer docs

Read error.code, error.action and error.details.issues before retrying. Preserve requestId when reporting a problem. Never include signer secrets in a report.

Code, cause and correction

Code	Cause	Corrective action	Retry
`INVALID_JSON`	Body is not valid JSON	Send one JSON object with the JSON content type	After fixing syntax
`INVALID_REQUEST`	Required or typed body fields failed validation	Correct each field in `details.issues`; check raw versus decimal units	After correcting fields
`INVALID_QUERY`	Order-list query is invalid	Check maker address, status and pagination	After correcting query
`INVALID_ORDER_ID`	Order ID cannot be parsed	Supply a valid order ID in the path	After correcting ID
`UPSTREAM_QUOTE_API_ERROR`	Swap quote could not be prepared	Check token pair, amount, routing inputs and quote service	After the cause changes; avoid a tight loop
`UPSTREAM_TRANSFER_PLAN_ERROR`	Transfer preparation failed	Check tokens, recipient resolution, runtime config and node health	After correcting input or recovery
`UPSTREAM_LIMIT_ORDER_ERROR`	Order plan or read failed upstream	Check order/maker and current node or service health	After correcting input or recovery

These are the codes emitted by the checked-in v2 handlers. A proxy or unsupported HTTP method may return a different response, including non-JSON; inspect status and content type before parsing. The former UPSTREAM_ROUTER_ERROR label is not the swap handler's current code.

Error envelope

Illustrative field-validation response:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Correct the request body fields before retrying /v2/swap-plans.",
    "action": "Update the listed fields and send the same request again.",
    "details": {
      "issues": [{ "field": "recipient", "message": "Provide recipient when mode is wallet_bound." }]
    },
    "requestId": "REQUEST_ID",
    "docsUrl": "https://vetrade.vet/developers/ai/overview"
  }
}

Endpoint coverage

Endpoint	Validation	Upstream failure
`POST /v2/swap-plans`	`INVALID_JSON`, `INVALID_REQUEST`	`UPSTREAM_QUOTE_API_ERROR`
`POST /v2/transfer-plans`	`INVALID_JSON`, `INVALID_REQUEST`	`UPSTREAM_TRANSFER_PLAN_ERROR`
`POST /v2/limit-order-plans`	`INVALID_JSON`, `INVALID_REQUEST`	`UPSTREAM_LIMIT_ORDER_ERROR`
`GET /v2/limit-orders`	`INVALID_QUERY`	`UPSTREAM_LIMIT_ORDER_ERROR`
`GET /v2/limit-orders/{orderId}`	`INVALID_ORDER_ID`	`UPSTREAM_LIMIT_ORDER_ERROR`

Technical coverage checked against website/functions/v2 on 23 October 2026. MCP wraps tool failures in its own JSON-RPC/tool response; inspect field issues there too. A warning inside a successful plan is not the same as a failed HTTP request.

Safe retry boundary

Planning retries do not broadcast transactions. A local execution timeout is different: inspect the transaction ID, receipt and local execution cache before another submission. Do not clear execution state merely to make an error disappear.

Fix swap units · Transfer recipient rules · Limit-order tasks · MCP troubleshooting.