Errors and troubleshooting
Every error message from the platform is a sentence written for a human, not a numeric code. This page is organised as "symptom → cause → what to do", using readable category names so you can act on it directly.
HTTP statuses and categories
The Open API is called by programs, so it uses real HTTP status codes; you can route on them without parsing the body:
| Category | Typical status | Symptom | What to do |
|---|---|---|---|
| Invalid API KEY | 401 | "API KEY 无效或已失效，请核对请求头 X-Pay-Api-Key" | Check the header name, any whitespace in the KEY, and whether it was rotated. We do not distinguish failure causes, precisely so that "this KEY exists" is not leaked |
| Merchant state not allowed | 403 | A specific reason (e.g. online collection not enabled, merchant suspended) | This is a readable reason, not a KEY problem. Follow it to apply for access or contact the platform |
| Platform temporarily unavailable | 503 | Internal server error | Not your fault; retry on your own schedule. A 503 should not make you rotate your KEY |
| Rate limited | 429 | "too many requests" | Slow down or add backoff. Creation is limited per merchant, queries have a wider allowance; counters are tracked per source IP and per merchant number |
| Invalid parameters | business code + readable msg | e.g. "missing merchant order number (merchantOrderNo)" | Fix the request body per the message |
| Order rejected | business code + readable msg | e.g. "amount below the minimum" | Rejection reasons are passed through verbatim; fix and retry. These do not consume idempotency |
Route on the status, read the msg for detail
Use the status code to decide whether to fix configuration, wait, or fix a parameter; use msg for the specific reason. Both are provided because programs and humans need different granularity.
Common issues
| Symptom | Likely cause | Troubleshooting order |
|---|---|---|
| Invalid API KEY | Wrong header name (it is X-Pay-Api-Key, not Authorization); leading/trailing whitespace in the KEY (common when read from an env var); KEY rotated past the grace window | 1) Log the header name and the last 4 characters of the KEY 2) Check the env var for quotes or newlines 3) Check whether the KEY was just rotated |
| Amount below the minimum | The amount is below the token's configured minimum | 1) Read minAmount from the chain and token list 2) Confirm amount is a decimal string in token units (Open API), not a smallest-unit integer |
| Wrong amount shape | The Open API wants "100.5"; the checkout endpoint wants "100000000" — they are opposite | 1) Confirm which endpoint you are calling 2) Check the order of magnitude against decimals; a factor of ten is usually this |
| Idempotent replay | The same merchantOrderNo was sent twice; the existing order is returned with idempotentReplay=true | This is normal behaviour, not an error. To genuinely create another order, use a new merchantOrderNo |
| Rate limited | Too many requests in a short window | 1) Confirm it is not a retry storm (idempotent retries count too) 2) Add exponential backoff 3) If it is a steady-state need, contact us to adjust the tier |
| Callback URL unreachable | Domain changed, unreachable during a deploy, firewall rule changed, or a private address | 1) Can it be reached from the public internet? 2) Does it accept POST? 3) Is it http(s)? 4) Does it respond within the timeout (about 10s)? |
| Callback signature fails | Body parsed and re-serialised; timestamp concatenated incorrectly; key is not the API KEY; not updated after rotation | 1) Sign the raw body bytes 2) Concatenate timestamp + body as strings 3) Confirm the key is the current API KEY |
| Order stuck at "pending" | The buyer has not transferred, sent to a different address, or the amount/identify data is wrong | 1) Query receivedAmountMinimal 2) Confirm the buyer used payAddress + payAmountMinimal + identify 3) Confirmations are slow when the chain is congested |
| "Submitted" for a long time | Confirmations not yet met | Check confirmations / requiredConfirmations. "Submitted" does not mean paid; do not ship in this state |
| "Manual" state | An on-chain payment cannot be attributed to exactly one order (e.g. two identical amounts to one address) | The system deliberately does not guess — guessing would mark order A as paid while order B never gets its money. Contact us for a manual claim |
| Amount off by a little | Smallest unit treated as token units, or vice versa; or floating-point conversion | Compare integer strings in the smallest unit; never use floats |
Check these first
- Which group of endpoints are you calling? The Open API needs an API KEY, merchant-side endpoints need a JWT, and public checkout endpoints need no login — the wrong group gives you a
401. - The amount shape. The Open API takes a decimal string; the checkout endpoint takes a smallest-unit integer string. A wrong order of magnitude usually means this.
- Compare order states by name, not by numeric size. The values are not ordered by degree of payment.
- A callback is not proof that money arrived. Verify with Query order before critical actions.
Need a human
Not yet available
Anonymous live chat is not live yet. For anything not covered above, contact us through the website registration entry point or by email, including your merchantNo and the relevant orderNo so we can locate it quickly.