错误与约定
响应包
所有接口返回同一响应包。成功时 ok 为 true、data 为载荷；失败时 ok 为 false，错误信息嵌在 error 下：error.code 是稳定的业务码，error.message 是给开发者的提示（不要直接展示给终端用户——请按 error.code 映射你自己的文案），error.details 是机器可读的补充事实。requestId 用于联系支持时定位这次请求。
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…" }需要处理的业务码
| HTTP | code | 场景 |
|---|---|---|
| 400 | CASH_QUOTE_AMOUNT_BELOW_MINIMUM | fromAmount 低于路线最小值；见 error.details.minimum |
| 400 | CASH_QUOTE_AMOUNT_ABOVE_MAXIMUM | fromAmount 高于最大值；见 error.details.maximum |
| 400 | CASH_QUOTE_PARAMETERS_REQUIRED / CASH_QUOTE_AMOUNT_INVALID | 报价字段缺失、未知币种或网络、金额非十进制 |
| 400 | CASH_ORDER_RECEIVING_ADDRESS_REQUIRED / CASH_ORDER_RECEIVING_ADDRESS_INVALID | 接收地址缺失或不符合接收网络格式 |
| 400 | CASH_QUOTE_EXTRA_FIELDS_INVALID | 需要 memo/tag 的网络缺失或格式错误 |
数据约定
- 金额为资产自身单位的十进制字符串（
"0.0125"），不是浮点数，也不是最小单位整数。 - 币种与网络使用币种接口返回的值（
symbol大写、network小写，如USDT/bsc）。 - 时间戳为毫秒；以
Iso结尾的字段为 ISO 8601 字符串。 - 幂等：
POST …/orders必须带Idempotency-Key；同 Key 重放返回首次响应并附Idempotency-Replayed头。 - 缓存：公开
/content/*响应带短时边缘缓存；商户接口响应从不缓存。