Error codes
When you create an order, ST Pay performs its checks in the following order. If a request violates more than one rule, only the first error is returned:
Signature → timestamp → source IP → merchant status → required fields and formats → callback_url environment and address rules → per-transaction minimum and maximum → duplicate merchant order number → (collection) pending order limit per member → (collection) receiving account and tail allocation / (payout) balance.
Before all of these: if the body is not a JSON object or Content-Type is not application/json, invalid_parameter is returned immediately; a request without api_identity or sign returns invalid_signature.
The message value is returned in Traditional Chinese and is intended for humans to read; its wording may change. Your program must use code to determine the result. In the table below, the last column starts with the English meaning of each message in quotation marks.
code | HTTP | message | Cause and what to do |
|---|---|---|---|
invalid_signature | 401 | 簽章驗證失敗 | "Signature verification failed." api_identity is wrong, the credential has been disabled, or the signature does not match. Check your code against the signature example, and make sure you are using the credential for the correct environment. Sending a field value as a number or boolean returns this error or invalid_parameter, so send every value as a string. A request without api_identity or sign returns it too. |
timestamp_expired | 400 | 請求時間與伺服器時間相差超過 5 分鐘，請校正您的伺服器時間（伺服器目前時間：yyyy-MM-dd HH:mm:ss） | "The request time differs from the server time by more than 5 minutes. Please correct your server time (current server time: yyyy-MM-dd HH:mm:ss)." timestamp differs from the ST Pay server time by more than 5 minutes (in either direction). The message includes the current server time so you can see the difference. Enable NTP to keep your server time accurate, and take the time and sign right before sending. |
ip_not_allowed | 403 | 來源 IP 不在白名單 | "Source IP is not on the whitelist." Check your server's actual egress IP, and ask ST Pay to add it to the whitelist; it takes effect in about 1 minute. If the source IP is not on any whitelist, the request is blocked at the gateway: it returns HTTP 403 with an HTML body instead of JSON. The fix is the same. |
merchant_disabled | 403 | 商戶已停用 | "Merchant is disabled." Orders cannot be created while the merchant is disabled. Contact ST Pay. |
permission_denied | 403 | 無此操作權限 | "No permission for this operation." Usually caused by a misspelled path under /api/v1/. Using GET, or a path outside /api/v1/, gets HTTP 404 with a non-JSON body directly from the gateway. |
missing_parameter | 400 | 缺少必填欄位 | "Required field missing." A required field was not sent, is null, or is an empty string; callback_url is whitespace only; a bank transfer payout is missing a bank field; or an order query did not include any order number. |
invalid_parameter | 400 | 欄位值不合法 | "Invalid field value." A field value has an invalid format, length, characters, or enumerated value; a field value is not a string; the body is not a valid JSON object, or Content-Type is not application/json; callback_url has an invalid format (see Callback URL for the rules); an FPS payout includes bank fields; or the bank code is not in the list. |
invalid_amount | 400 | 金額格式不正確 | "Incorrect amount format." The amount is 0, negative, has more than 2 decimal places (counted literally, so 1000.500 has 3), is greater than 9999999999999999.99, or is not a number. |
missing_member_identity | 400 | 請提供會員唯一識別或真實姓名 | "Please provide the member's unique identifier or real name." Neither merchant_user_id nor payer_name was sent when creating a collection order. |
invalid_callback_url | 400 | Callback 網址不符合規定：不可為本機或內網位址 | "The Callback URL is not allowed: it must not be a local or private network address." The host of the callback_url sent when creating the order is local, a private network address, an internal domain, or a non-standard IP notation. See Callback URL. Format errors (a value that is not a URL, is longer than 500 characters, contains whitespace, or breaks another format rule in that section) return invalid_parameter. |
amount_out_of_range | 422 | 金額超出限額 | "Amount exceeds the limits." The original amount or payout amount is outside the per-transaction minimum and maximum. |
merchant_order_no_duplicate | 409 | 商戶單號重複 | "Duplicate merchant order number." See Duplicate requests and confirming results. |
user_active_orders_limit | 422 | 有效訂單已達上限 | "Active order limit reached." The same member already has 10 pending collection orders. Wait until one of them completes or expires before creating another. |
channel_full | 422 | 通道已滿，請輸入其他金額再試 | "Channel is full. Please enter a different amount and try again." For the same channel and the same original amount, all identification tails are already taken by pending orders. Ask the payer to try again with a different amount. |
no_available_card | 422 | 通道已滿，請輸入其他金額再試 | "Channel is full. Please enter a different amount and try again." The channel currently has no available receiving account. Try again later or use the other channel. If this keeps happening, contact ST Pay. |
insufficient_balance | 422 | 商戶餘額不足 | "Insufficient merchant balance." When creating a payout order, the available balance is less than the payout amount plus the fee. |
order_not_found | 404 | 查無此單 | "Order not found." The order does not exist, does not belong to you, or has been deleted after the retention period. |
query_conflict | 400 | 訂單號與商戶單號指向不同訂單 | "The order number and merchant order number refer to different orders." Both order numbers were sent in an order query, but they do not refer to the same order. |
internal_error | 500 | 系統錯誤，請以商戶單號查單確認結果 | "System error. Please query by merchant order number to confirm the result." An internal ST Pay error; the order may or may not have been created. Do not simply treat it as a failure. Query by merchant order number to confirm. |
channel_full and no_available_card have the same message; use code to tell them apart.
If you get invalid_parameter, invalid_signature, or a similar error and cannot find the cause, give your ST Pay integration contact your api_identity, the merchant order number (or, for a query, the order number you queried), and the time (UTC+8). ST Pay can look up the API error log, which shows which field was rejected or why the signature failed. ST Pay only logs requests with a valid api_identity; if the api_identity itself is wrong, nothing is logged, so check it first.