Errors & conventions

On this page

Response envelope
Business codes you should handle
Data conventions

Response envelope

Every endpoint returns the same envelope. On success ok is true and data holds the payload. On failure ok is false and the problem is nested under error: error.code is a stable business code, error.message is a developer hint (do not show it to end users — map error.code to your own copy) and error.details carries machine-readable facts. requestId identifies the request when you contact support.

json

{ "ok": true, "data": { "quoteId": "quote_…" } }

json

{ "ok": false, "error": { "code": "CASH_QUOTE_AMOUNT_BELOW_MINIMUM", "message": "…", "details": { "minimum": "1.042", "currency": "USDT", "source": "provider" } }, "requestId": "7f1c…" }

Business codes you should handle

HTTP	code	When
400	`CASH_QUOTE_AMOUNT_BELOW_MINIMUM`	`fromAmount` under the route minimum; `error.details.minimum`
400	`CASH_QUOTE_AMOUNT_ABOVE_MAXIMUM`	`fromAmount` over the maximum; `error.details.maximum`
400	`CASH_QUOTE_PARAMETERS_REQUIRED` / `CASH_QUOTE_AMOUNT_INVALID`	missing quote fields, unknown symbol or network, non-decimal amount
400	`CASH_ORDER_RECEIVING_ADDRESS_REQUIRED` / `CASH_ORDER_RECEIVING_ADDRESS_INVALID`	missing or malformed receiving address for the target network
400	`CASH_QUOTE_EXTRA_FIELDS_INVALID`

Data conventions

Money is a decimal string in the asset's own unit ("0.0125"), never a float and never base units.
Symbols and networks are the values returned by the currencies endpoint (symbol is upper-case, network lower-case, e.g. USDT / bsc).
Timestamps are epoch milliseconds; fields ending in Iso are ISO 8601 strings.
Idempotency: POST …/orders requires Idempotency-Key; a replay with the same key returns the first response with an Idempotency-Replayed header.
Caching: public /content/* responses are edge-cached for a short interval; merchant responses are never cached.