Skip to main content
This page documents all error codes returned by the OpenAPI platform. Use this reference to understand error responses and implement appropriate handling.

​
Result Status Values

All API responses include a result object with a resultStatus field:
StatusMeaningAction
SSuccessRequest completed successfully
FFailedRequest failed, check resultCode for details
UUnknownResult unknown, retry or poll for status
AAcceptedRequest accepted, processing asynchronously

​
Common Error Codes

These error codes may appear across multiple APIs:

​
Authentication & Authorization

CodeStatusDescriptionResolution
INVALID_SIGNATUREFRequest signature validation failedVerify signing algorithm and key
INVALID_CLIENTFClient ID not recognizedCheck Client-Id header
INVALID_ACCESS_TOKENFAccess token invalid or expiredRefresh or re-authorize
EXPIRED_ACCESS_TOKENFAccess token has expiredUse refresh token
INSUFFICIENT_SCOPEFToken lacks required permissionsRequest additional scopes
UNAUTHORIZEDFNot authorized for this operationCheck credentials

​
Request Validation

CodeStatusDescriptionResolution
PARAM_ILLEGALFOne or more parameters invalidCheck request parameters
MISSING_REQUIRED_PARAMFRequired parameter not providedAdd missing parameter
INVALID_AMOUNTFAmount format or value invalidCheck amount format
INVALID_CURRENCYFCurrency code not supportedUse valid ISO-4217 code
REQUEST_TIME_INVALIDFRequest timestamp out of rangeSync server clock

​
Rate Limiting

CodeStatusDescriptionResolution
REQUEST_TRAFFIC_EXCEED_LIMITURate limit exceededImplement backoff and retry
SYSTEM_BUSYUSystem under heavy loadRetry after delay

​
System Errors

CodeStatusDescriptionResolution
UNKNOWN_EXCEPTIONUUnexpected system errorRetry with exponential backoff
PROCESS_FAILFProcessing failedRetry the request
SERVICE_UNAVAILABLEUService temporarily unavailableRetry later

​
Payment-Specific Error Codes

​
Payment Creation

CodeStatusDescriptionResolution
ORDER_NOT_EXISTFPayment/order not foundVerify payment ID
ORDER_IS_CLOSEDFOrder already completed or cancelledCreate new order
ORDER_STATUS_INVALIDFOrder in invalid stateCheck order status
REPEAT_REQ_INCONSISTENTFDuplicate request with different paramsUse new paymentRequestId
PAYMENT_IN_PROCESSUPayment being processedPoll for status

​
Payment Processing

CodeStatusDescriptionResolution
INVALID_AUTH_CODEFPayment auth code invalid/expiredCustomer refreshes QR
INSUFFICIENT_BALANCEFCustomer has insufficient fundsInform customer
RISK_REJECTFRejected by risk systemContact support
USER_NOT_EXISTFUser account not foundVerify user ID
PAYMENT_TIMEOUTFPayment timed outCreate new payment

​
Refunds

CodeStatusDescriptionResolution
REFUND_AMOUNT_EXCEEDFRefund exceeds available amountCheck refund amount
REFUND_NOT_ALLOWEDFPayment cannot be refundedCheck payment state
REFUND_IN_PROCESSURefund being processedPoll for status
REFUND_NOT_EXISTFRefund record not foundVerify refund ID

​
Void

CodeStatusDescriptionResolution
VOID_NOT_ALLOWEDFPayment cannot be voidedUse refund instead
ORDER_ALREADY_SETTLEDFPayment already settledUse refund instead
VOID_IN_PROCESSUVoid being processedPoll for status

​
Capture

CodeStatusDescriptionResolution
CAPTURE_AMOUNT_EXCEEDFExceeds authorized amountCheck capture amount
AUTHORIZATION_EXPIREDFPre-authorization expiredCreate new authorization
CAPTURE_IN_PROCESSUCapture being processedPoll for status

​
Authorization-Specific Error Codes

CodeStatusDescriptionResolution
INVALID_AUTH_CLIENTFAuth client configuration invalidCheck client setup
INVALID_AUTH_CLIENT_STATUSFAuth client disabledContact support
INVALID_CODEFAuthorization code invalidRequest new auth
EXPIRED_CODEFAuthorization code expiredRequest new auth
USED_CODEFAuthorization code already usedUse existing tokens
INVALID_REFRESH_TOKENFRefresh token invalidRe-authorize user
EXPIRED_REFRESH_TOKENFRefresh token expiredRe-authorize user
AUTH_CLIENT_UNSUPPORTED_GRANT_TYPEFGrant type not supportedCheck grantType value

​
Message-Specific Error Codes

CodeStatusDescriptionResolution
USER_NOT_SUBSCRIBEDFUser disabled notificationsCannot send
MESSAGE_CONTENT_INVALIDFMessage content violates policyReview content
SENDINGUMessage queued for deliveryWill be delivered

​
Error Handling Best Practices

1

Check Result Status

First check resultStatus to determine if the request succeeded
2

Handle by Status

  • S: Process successful response
  • F: Handle failure based on resultCode
  • U: Implement retry or polling logic
  • A: Wait for async completion
3

Log Details

Log resultCode and resultMessage for debugging
4

User Communication

Map technical errors to user-friendly messages

​
Example Error Handling

async function handleAPIResponse(response) {
  const { result } = response;

  switch (result.resultStatus) {
    case 'S':
      return { success: true, data: response };

    case 'F':
      // Categorize failures
      if (['INVALID_SIGNATURE', 'INVALID_CLIENT', 'UNAUTHORIZED'].includes(result.resultCode)) {
        throw new AuthenticationError(result.resultMessage);
      }
      if (['PARAM_ILLEGAL', 'MISSING_REQUIRED_PARAM'].includes(result.resultCode)) {
        throw new ValidationError(result.resultMessage);
      }
      if (['INSUFFICIENT_BALANCE', 'RISK_REJECT'].includes(result.resultCode)) {
        throw new PaymentDeclinedError(result.resultCode, result.resultMessage);
      }
      throw new APIError(result.resultCode, result.resultMessage);

    case 'U':
      // Unknown status - may need retry or polling
      if (result.resultCode === 'REQUEST_TRAFFIC_EXCEED_LIMIT') {
        throw new RateLimitError('Rate limit exceeded');
      }
      return { success: false, pending: true, shouldRetry: true };

    case 'A':
      // Accepted for async processing
      return { success: false, pending: true, shouldPoll: true };

    default:
      throw new APIError('UNKNOWN_STATUS', `Unknown status: ${result.resultStatus}`);
  }
}