Error codes
On errors the HTTP status is still 200 and code in the body is not 0:
json
{ "code": 40005, "message": "Request IP 203.0.113.10 is not in the merchant whitelist" }message is an English description and may contain values. Branch on code, not on the message text.
Codes
| code | Meaning | What to do |
|---|---|---|
| 0 | Success | |
| 400 | Business failure — typically insufficient USDT balance, a payment provider error, or operation failed | Read message; top up if the balance is insufficient |
| 500 | Internal platform error (message is always a generic text) | Retry later. For orders and payouts, first check with Get order whether it was created |
| 40000 | Decryption failed, or a required parameter is missing (merchant order number, cardId, query period… see message) | Check you use the latest public key with PKCS#1 v1.5 padding, and that parameters are complete |
| 40001 | Merchant number not found | Check merchantNo |
| 40002 | Merchant disabled | Contact the platform |
| 40003 | OpenAPI not enabled for this merchant | Contact the platform |
| 40004 | No callback URL configured | Set it in the merchant console or pass callbackUrl |
| 40005 | Request IP not whitelisted | Add your server's outbound IP in the merchant console |
| 40007 | Duplicate merchant order number | Use a new number; if this is a retry after a timeout, query the original order first |
| 40010 | Currency not supported (unknown or disabled) | Check currencyType |
| 40011 | No matching pool available | Contact the platform |
| 40012 | No trader can take this amount right now, or the amount is out of range | Try another amount or later |
| 40013 | Not enough available quota | Try another amount or later |
| 40015 | Customer is blacklisted, or the customer / region is not supported | Don't create orders for this customer |
| 40016 | Payout / payment method not supported | Use the codes from List payout methods |
| 40017 | Currency not enabled for your account | Contact the platform |
| 40018 | Recipient details don't meet the method's requirements (message says which) | Follow the field rules from List payout methods |
| 40019 | Invalid amount: must be greater than 0 with at most two decimals | Fix the amount |
| 40020 | Order not found | Check the merchant order number; you can only see your own orders |
| 40021 | The order's current state doesn't allow this (e.g. an order marked as paid can't be cancelled) | Query the order state first |
| 40023 | cardId is not a receiving account assigned to this order | Use a cardId from cards returned by own-checkout order creation |
When a request times out
If creating an order or payout times out, don't create a new order with a new merchant order number right away. Query with the original number via Get order: if it exists, it was created; if you get 40020, retry with the same merchant order number — the platform rejects duplicates with 40007.