Error codes catalogue
Errors catalogue
Stable contract: success+msg+traceId.codevalues are still being unified — use message semantics +traceIdfor support.
How to decide success/failure
| Case | Rule |
|---|---|
| Success | success == true |
| Business failure | success == false; HTTP may still be 200 |
| Support | Always keep traceId |
msg, not message. Envelope: response-envelope.Retry matrix (with idempotency)
| Category | Typical signal | Same key retry? | Merchant action |
|---|---|---|---|
| Auth failure | signature / unauthorized / timestamp | Re-sign; may reuse business key | Fix clock / signature |
| Validation | mandatory / required / invalid | No — new key | Fix params |
| Amount out of range | out of range / between | No | Adjust amount; check pair limits |
| Pair not enabled | supported / not matched | No | Ask Customer Success |
| Quote expired | expire / expired | No | New get-quote |
| In-flight | processing | Do not change key | Wait webhook / query |
| Timeout / unknown | no response | Yes — same key | Backoff retry |
| Terminal fail | fail / rejected | No | Handle terminal state |
| System error | internal / 5xx-like | Same key OK on idempotent APIs | Ticket with traceId |
Convert amount example
{
"status": 500,
"code": "AMOUNT_OUT_OF_RANGE",
"msg": "sourceAmount must be between 100 and 500000 USDT, current: 10",
"success": false,
"traceId": "a1b2c3d4e5f6",
"data": null
}100–500000 is the USD-class default fallback — fiat pairs use configured min/max. See Convert · pairs & limits.STABLE_SWAP
{
"success": false,
"msg": "sourceAmount is required for STABLE_SWAP",
"traceId": "..."
}Wallet deposit whitelist (WalletErrorCode)
status 500 with an 8-digit numeric code.code | Meaning | Same key retry? |
|---|---|---|
10000100 | Transaction not found, or not owned by the caller | No — re-read GET /v1/wallet/transaction/list?whiteListStatus=init |
10000101 | Review already completed for this deposit | No — treat as done |
10000102 | Payer details incomplete | No — fix fields, new key |
10000103 | Field value not accepted, incl. invalid countryCode or unknown provider | No — send countryCode as ISO 3166-1 alpha-2 and take provider from /options |
10000104 | Cannot submit right now | Poll GET /v1/wallet/transaction/detail; do not edit and retry immediately |
10000105 | Duplicate request | No — read the first request's outcome |
10000106 | Source address supplied or changed for a received deposit | No — drop the address fields |
10000107 | Wallet invalid, or the sub-wallet has not been created | No — create the sub-wallet first |
Webhooks
eventId.