錯誤與約定
回應包
所有介面回傳同一回應包。成功時 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/*回應帶短時邊緣快取；商戶介面回應從不快取。