HTTP status codes and errors

Updated: 2026-08-21 02:20

Use HTTP status codes to decide the response category, then use response body error.code for the exact business or integration reason. Each API page lists the concrete error codes that can appear for that endpoint.

Response categories

2xx means the platform accepted and processed the API call. In v1 ordinary APIs, successful responses use 200. Create APIs have created an order or returned an existing idempotent order; merchants should read response body status, use the query API or wait for Webhook to determine the final business result.

4xx means the request has a merchant-side issue. The platform does not create a new order for rejected create requests. Merchants should correct parameters, credentials, permissions, product configuration or request frequency before retrying. For explicit business rejections such as insufficient balance, merchants can mark the merchant-side attempt failed according to their own order model.

HTTP 5xx, timeout, disconnect or an unverifiable response means you may not know whether the order was created. Query the same order type with the original merchantOrderNo. If repeated queries still find no order, resend the exact same business request with the same merchantOrderNo; never generate a new number or issue concurrent create retries.

Common HTTP status codes

HTTP status code	Description	How merchants handle	Typical error codes
200	API call succeeded. Create requests have been accepted or returned by idempotency; query requests succeeded.	Read the response body. For orders, use status, query API or Webhook to determine the business result.	None
400	Path, query, Header or Body validation failed.	Correct the request according to error.code and the endpoint field descriptions.	INVALID_REQUEST, INVALID_JSON, PARAMETER_INVALID, PARAMETER_MISSING, AMOUNT_FORMAT_INVALID
401	API Key, timestamp, random string or signature failed.	Check credentials, clock, signed payload and signing Header.	INVALID_API_KEY, INVALID_SIGNATURE, TIMESTAMP_INVALID, NONCE_REPLAYED
403	Merchant, credential or product permission rejected.	Check onboarding, product enablement and API Key status. Source-IP admission is managed operationally at the security group, WAF or API Gateway and is not an application error contract.	PERMISSION_DENIED, PRODUCT_NOT_ENABLED
404	Endpoint or merchant order was not found.	Confirm the endpoint path and original merchantOrderNo.	NOT_FOUND, ORDER_NOT_FOUND
409	Merchant order number conflicts with an existing business order.	Stop retrying with changed values and query the existing order.	MERCHANT_ORDER_NO_CONFLICT
413	Request body exceeded 64 KiB.	Reduce the request payload.	REQUEST_BODY_TOO_LARGE
415	Request body media format is not accepted.	Send a UTF-8 JSON body for POST requests.	UNSUPPORTED_MEDIA_TYPE
422	Business validation rejected the request.	Correct business fields such as amount, balance, product, recipient, bank or limits.	BUSINESS_REJECTED, INSUFFICIENT_BALANCE, AMOUNT_LIMIT_EXCEEDED, AMOUNT_PRECISION_INVALID, BANK_UNSUPPORTED, PRODUCT_UNSUPPORTED, COUNTRY_UNSUPPORTED, CURRENCY_UNSUPPORTED, RECIPIENT_INVALID
429	Requests are too frequent.	Slow down and query existing create attempts before sending more requests.	FREQUENCY_LIMITED
500	Internal service error for a non-create API.	Wait briefly, then retry the non-create request. A contract-valid create response does not use this status.	INTERNAL_ERROR
502	Gateway or upstream dependency returned an abnormal result for a non-create API.	Wait briefly, then retry the non-create request. If a create response cannot be verified, query with the original merchantOrderNo first.	GATEWAY_ERROR
503	A create result is explicitly unknown, or a non-create API/dependency is unavailable.	For ORDER_RESULT_UNKNOWN, query by the original merchantOrderNo; resend only the unchanged request with that same number if repeated queries still find no order.	ORDER_RESULT_UNKNOWN, SERVICE_UNAVAILABLE
504	Gateway or upstream dependency timed out for a non-create API.	Wait briefly, then retry the non-create request. If a create response cannot be verified, query with the original merchantOrderNo first.	GATEWAY_TIMEOUT

Error response body

Every error response uses a stable shape:

{
  "error": {
    "code": "PARAMETER_INVALID",
    "message": "amount.value must be a positive decimal string."
  }
}

All ordinary API responses include Request-Id in the response Header. Error responses include stable uppercase error.code in the response body. See basic rules for the full error body field description.

Common error code examples

HTTP status code	Error code	Description	How merchants handle
400	PARAMETER_INVALID	Request parameters do not match the endpoint contract.	Check the endpoint field descriptions and correct the request.
400	AMOUNT_FORMAT_INVALID	amount.value is not a positive decimal string.	Use a major-unit decimal string such as 100.50; do not send JSON numbers, scientific notation or negative values.
422	AMOUNT_PRECISION_INVALID	amount.value has more decimal places than allowed by the selected product and currency.	Adjust the amount according to the amountScale in supported countries and currencies.
401	INVALID_SIGNATURE	The signing Header did not pass verification.	Check API Key, timestamp, random string, request URL, request body and API Secret.
403	PERMISSION_DENIED	The merchant, key or product permission is not allowed.	Check onboarding, key status and product enablement in Merchant Portal.
404	ORDER_NOT_FOUND	No order exists for the merchant order number.	Confirm merchantOrderNo and query the correct order type.
409	MERCHANT_ORDER_NO_CONFLICT	The merchant order number already exists with different business values.	Query the existing order and stop retrying with changed values.
401	NONCE_INVALID	The nonce is missing or does not satisfy the request Header contract.	Generate a fresh nonce within the length limit and sign the request again.
422	COUNTRY_UNSUPPORTED	The requested country is not supported for this merchant or resource.	Use a supported country from the enabled product or balance catalog.
422	CURRENCY_UNSUPPORTED	The requested currency is not supported for this country, product or merchant.	Use a supported currency from the enabled product or balance catalog.
422	PRODUCT_UNSUPPORTED	The requested product is unavailable for this country, currency or merchant.	Use an enabled product code from Merchant Portal or the supported product-code catalog.
422	RECIPIENT_INVALID	Recipient account information failed validation.	Correct recipient fields before retrying.
422	INSUFFICIENT_BALANCE	The merchant account balance is insufficient for the payout.	Recharge, reduce amount or wait for funds before creating a new payout.
502	GATEWAY_ERROR	The upstream gateway returned an unexpected error or invalid response for a non-create API.	Wait briefly, then retry.
503	ORDER_RESULT_UNKNOWN	The platform could not confirm whether the create request produced an order; the error response has no platOrderNo.	Query the same order type with the original merchantOrderNo. If repeated queries still find no order, resend only the unchanged create request with that same merchantOrderNo.
503	SERVICE_UNAVAILABLE	A non-create API service or required dependency is temporarily unavailable.	Wait briefly, then retry.
504	GATEWAY_TIMEOUT	A non-create upstream gateway did not return a result before timeout.	Wait briefly, then retry.
429	FREQUENCY_LIMITED	Requests are too frequent.	Reduce request frequency and retry after a short wait.
500	INTERNAL_ERROR	Internal service error for a non-create API.	Wait briefly, then retry.

Troubleshooting information

For support, provide environment, UTC time, operation, HTTP status, the Request-Id response Header, response body error.code and merchant order number. Include referenceNo when the issue involves payer receipt matching or recipient institution investigation. Never send the Secret, signing Header values, recipient account or complete request body.