Error Codes

HTTP status indicates whether the API request succeeded. The response body's code/msg values are stable platform business codes.

When troubleshooting, log HTTP status, code/msg, traceId, request path, merchant order number, and the signed raw body hash.

Common Errors

HTTP 40012100007INVALID_FIELD

Missing required field, invalid format, or unknown field.

HTTP 40012100008UNSUPPORTED_CURRENCY

The currency is not supported.

HTTP 40012100009UNSUPPORTED_METHOD

The method or currency/method combination is not supported.

HTTP 40112100010UNAUTHORIZED

Signature is missing or invalid, timestamp expired, or credentials are not configured.

HTTP 40212100011INSUFFICIENT_BALANCE

Merchant balance is insufficient.

HTTP 40312100012METHOD_NOT_ENABLED

The method exists but is not enabled for this merchant.

HTTP 40412100013ORDER_NOT_FOUND

The order does not exist.

HTTP 404404NOT_FOUND

The requested Subscription object does not exist or does not belong to this merchant.

HTTP 40912100014IDEMPOTENCY_CONFLICT

For orders: merchantOrderNo is taken but the platform could not return its order. For Subscription APIs: the request differs from the one that first used this merchantPlanNo / merchantSessionNo / clientRequestId, or the resource state rejects the operation.

HTTP 42912100015RATE_LIMITED

Request rate is limited.

HTTP 50012100016INTERNAL_ERROR

Internal error.

HTTP 50312100017SERVICE_UNAVAILABLE

Dependency unavailable or upstream timeout.

HTTP 50312100020CHANNEL_BUSY

The payment channel is temporarily rate limiting. The order was not created: resend the same request with the same merchantOrderNo after a back-off. No query is needed first.

Handling Guidance

INVALID_FIELD

Fix the field, format, method branch, or required rule according to data.message.

UNAUTHORIZED

Check Access Key, the Ed25519 private key against the uploaded public key, the created/expires window, nonce reuse, Content-Digest, and the platform body key id.

IDEMPOTENCY_CONFLICT

merchantOrderNo is taken but the platform could not return its order. Query that number and keep querying; do not allocate a new one. Order creation never compares fields, so this is not a signal that the request differs.

RATE_LIMITED

Reduce request frequency and avoid repeated short-interval queries for the same order.

5xx / connection broken

Do not switch to a new order number immediately. Query first to confirm whether the order was created.

Subscription API: HTTP And Operation

Subscription create and change APIs can return HTTP 200 with an operation object. HTTP status describes the API call; operation.status describes the recorded side effect. Treat FAILED, CHANNEL_UNKNOWN, PENDING, and RUNNING as non-successful Operation results even when HTTP is 200.

Subscription APIs behave differently from order creation: they do compare the request against the one that first used the same merchantPlanNo, merchantSessionNo or clientRequestId, and reject a differing one with IDEMPOTENCY_CONFLICT. The current resource state can reject the operation with the same code. Query the original Subscription object first.

For HTTP 500 and 503, data.message is intentionally generic. Record traceId, the relevant merchant business number, and operationNo when present; do not replace the business number and create a duplicate object.