Virtual Account OpenAPI Error Codes

5. Error Responses

5.1 Error Response Format

{
  "code": 10010000,
  "message": "virtual_account parameters error",
  "data": null
}

The caller must check the code field in the response body:

code = 0: The request was processed successfully.

code != 0: The request failed. Refer to the error code descriptions below for details.

5.2 Error Code Reference

HTTP Status	Business Error Code	Error Message	Description	Recommended Action
400	`10010000`	Invalid parameters	A required parameter is missing, or a parameter has an invalid type, format, length, or value	Correct the request parameter indicated in the response `message`
400	`10010000`	Invalid virtual account number	`virtual_account` is not a string containing 7–15 digits	Check the number length and remove spaces, letters, or special characters
400	`10010000`	Invalid pagination parameters	`page_number` is less than 1, or `page_size` is outside the range of 1–100	Correct the pagination parameters and retry
400	`10010000`	Invalid request format	The request body is not valid JSON, or a field has an invalid type	Check the JSON syntax, field types, and `Content-Type`
400	`30010011`	Missing required merchant field	A valid Merchant ID cannot be obtained from the Access Token	Verify the merchant information associated with the Access Token
401	`30010002`	Invalid access token	The Access Token is invalid, malformed, or expired	Obtain a new Access Token and retry
401	`10010004`	Invalid signature	The request signature is missing or signature verification failed	Check the signing algorithm, signing key, and parameters included in the signature
403	`10000004`	Permission denied	The current merchant is not authorized to call this API	Contact the platform to request access
403	`30010020`	Invalid merchant status	The merchant does not exist, has not passed verification, or has been suspended	Verify the merchant status or contact the platform
404	`10090002`	Virtual account not found	The VA does not exist, does not belong to the current merchant, has a mismatched VA type, or is not in an available status	Check the VA number, merchant ownership, VA type, and VA status
409	`30010013`	External ID already exists	The current merchant has already submitted a creation request using the same `external_id`	Query the result of the original request instead of creating another VA
422	`30010014`	Merchant fee not found	No VA service fee is configured for the merchant, or no fee configuration matches the current VA type	Contact the platform to configure the VA service fee
500	`10000000`	System error	An unknown internal platform error occurred	Record the request details and occurrence time, then contact technical support
500	`10090000`	Failed to create virtual account	The platform or payment channel failed to create the VA	Query the creation result later and retry only after confirming that the original request failed
500	`-1`	Internal runtime error	A runtime exception occurred that was not mapped to a specific business error code	Record the request details and occurrence time, then contact technical support
502	`Downstream response code`	Payment channel error	The bank or payment channel returned a business error. The specific code and message are determined by the channel	Handle the error according to the response `message`; contact the platform if the error is unknown
503	`10000001`	Service maintenance	The VA service is under maintenance or temporarily unavailable	Retry later according to the platform notice or the `Retry-After` header

10010000 is the general parameter validation error code. Use the response message to identify the invalid parameter.

Error code 10010004 is defined for signature errors, but application-level HMAC verification is not currently enabled for the VA APIs. This error may still be returned if signature verification is enabled at the API gateway.

Some downstream errors during VA creation are caught internally by the Service layer. The API may therefore return code = 0 while data.status indicates failure and data.virtual_account is empty. The caller must not rely on code alone.

6. Error-Handling Recommendations

6.1 Errors That Must Not Be Retried Immediately

The following errors require the caller to correct the request, credentials, permissions, or merchant configuration before retrying:

10010000: Correct the request parameters.

10010004: Correct the request signature.

10000004: Request permission to access the API.

30010002: Obtain a new Access Token.

30010011: Check the merchant information in the Access Token.

30010013: Query the original request instead of creating another VA.

30010014: Contact the platform to configure the VA service fee.

30010020: Verify the merchant’s verification or suspension status.

10090002: Check the VA number and merchant ownership.

6.2 Errors That May Be Retried with Caution

The following errors may be retried using an exponential backoff strategy:

10000000: Internal system error.

10000001: Service maintenance.

10090000: VA creation failure.

HTTP 429: Request rate limit exceeded.

HTTP 500: Internal platform error.

HTTP 502: Payment channel temporarily unavailable.

HTTP 503: Service temporarily unavailable.

Recommended retry strategy:

Wait 1 second after the first failure.

Wait 2 seconds after the second failure.

Wait 4 seconds after the third failure.

Retry no more than three times.

If the response contains a Retry-After header, follow the delay specified by that header.

6.3 Special Handling for VA Creation

After submitting a VA creation request, the caller should check the following in order:

Whether code is 0.

Whether data.status indicates success.

Whether data.virtual_account is non-empty.

Whether a processing record already exists for the same external_id.

Example:

7. Important Notes

virtual_account must be provided as a string.

virtual_account must contain 7–15 digits.

We recommend validating the VA number using the regular expression ^[0-9]{7,15}$.

A unique external_id must be used when creating a VA.

external_id should be used as the idempotency identifier for the creation request.

Do not determine the business result from the HTTP status code alone. Always check the response code.

For VA creation, also check data.status and data.virtual_account.

An empty payment record list is a valid result and should not be treated as a system error.

Amount fields must be handled as strings or fixed-point decimal values. Do not use floating-point arithmetic for monetary calculations.

10.

Do not record complete Access Tokens, signing keys, or other sensitive credentials in logs.

Virtual Account Error Codes

Virtual Account OpenAPI Error Codes#

5. Error Responses#

5.1 Error Response Format#

5.2 Error Code Reference#

6. Error-Handling Recommendations#

6.1 Errors That Must Not Be Retried Immediately#

6.2 Errors That May Be Retried with Caution#

6.3 Special Handling for VA Creation#

7. Important Notes#