Error codes

There are two types of errors: API request errors, and Payment errors. API request errors represent that the API invocation was not complete successfully for some reason. Although the API request succeeded, but if gateway processing such as charge or refund fails, payment error will occur.

API request errors

This errors represent that the API request was not accepted normally. API returns status code of 4xx or 5xx family.

HTTP StatusDescription
400 Bad RequestsInvalid content of the request. Details are provided in the body error information.
401 UnauthorizedAuthentication failed. Authorization header is missing or has invalid content.
403 ForbiddenNot enough permission to execute the request.
404 Not FoundThe specified path or resource does not exist.
429 Too Many RequestsExceeded the API Limits.
500 Internal Server ErrorUnexpected error occurred in our system. The processing may have been partially executed.

In most case, detail error information is provided with the following JSON format:

  • status (string) – Type of response (Usually error)
  • code (string) – Error code
  • errors – Array of following object:
    • field (optional, string) – Request parameter name where the error occurred
    • reason (string) – Detail reason of the error

Ex. when only HTTP Status code is provided:

HTTP/1.1 429 Too Many Requests
...
Content-Length: 0

Ex. when JSON error information that has only error code is provided:

HTTP/1.1 400 Bad Requests
...
Content-Type: application/json
...

{
    status: "error",
    code: "NON_UNIQUE_ACTIVE_TOKEN"
    errors: []
}

Ex. when JSON error information with detail error reason and field name is provided:

HTTP/1.1 400 Bad Requests
...
Content-Type: application/json
...

{
    status: "error",
    code: "VALIDATION_ERROR"
    errors: [{
        field: "card_number"
        reason: "INVALID_CARD_NUMBER"
    }]
}

Ex. when JSON error information with detail error reason is provided:

HTTP/1.1 400 Bad Requests
...
Content-Type: application/json
...

{
    status: "error",
    code: "CHARGE_AMOUNT_TOO_LOW"
    errors: [{
        reason: "Charge amount must exceed 100"
    }]
}

Error codes of API request errors

The error codes in the JSON error information are defined in the table below.

HTTP StatusError codesDescription
400ALREADY_CAPTUREDThe subject charge is already captured or not authorized successfully.
400AUTH_NOT_SUPPORTEDGateway that support authorization is not configured.
400CANCEL_NOT_ALLOWEDThis payment method is not support cancel. Or the state of this charge is not cancelable. For detail refer cancels.
400CANNOT_CHANGE_CANCELED_SUBSCRIPTIONCanceled subscription can not be modified.
400CANNOT_CHANGE_TOKENTransaction token of this state subscription can not be changed. For conditions that allow you to change the transaction token of subscription, see update a subscription.
400CANNOT_REFUND_UNSUCCESSFUL_CHARGECharges other than successful state can not be refunded.
400CAPTURE_AMOUNT_TOO_LARGECapture amount can not be larger than the amount when it was authorized.
400CARD_BRAND_NOT_SUPPORTEDGateway that support the requested card brand is not configured.
400CARD_COUNTRY_NOT_SUPPORTEDGateway that allow the requested card country is not configured.
400CARD_PROCESSING_DISABLEDCard payments is disabled as payment type.
400CHARGE_TOO_QUICKExceeded the usage limit of the recurring token. See (Recurring tokens).
400CONVENIENCE_PROCESSING_DISABLEDConvienence is disabled as payment type.
400CURRENCY_MUST_MATCH_CHARGECurrency when refund must be the same as when it was charged.
400CVV_REQUIREDCVV required.
400CVV_AUTHORIZATION_NOT_COMPLETEDCVV (security code) authentication failed.
400FILE_INVALID_TYPEMIME type of uploaded file is invalid.
400FILE_MAX_SIZE_EXCEEDEDUploaded file size is too large.
400FORBIDDEN_IPThe country identified by the source IP is not in allowed countries.
400INSTALLMENT_MAX_PAYOUT_PERIOD_EXCEEDEDThe payment period of installment payment exceeds the max payout period.
400INSTALLMENT_PAYMENT_TYPE_NOT_ALLOWED_FOR_PLANThe payment type is not allowed as installment payment.
400INSTALLMENT_INVALID_CYCLES_COUNTThe specified number of installments is not available.
400INSTALLMENT_INVALID_PLANThe installment plan is not supported.
400INVALID_FORMAT_MERCHANT_TRANSACTION_IDThe merchant transaction ID provided was in an unacceptable format.
400INVALID_PLATFORMSpecified platform is not valid.
400INVALID_TOKEN_TYPEType of transaction token is wrong.
400INVALID_QR_SCAN_GATEWAYGateway that support QR code payment is not configured or is not available.
400LAST_NAME_REQUIREDLast name is required.
400LIVE_MODE_NOT_ENABLED_WHEN_UNVERIFIEDTo use live mode, you need to be verified.
400MERCHANT_TRANSACTION_ID_UNACCEPTED_FOR_BRANDThe brand to be used does not support the merchant_transaction_id field
400NO_DIRECT_CURRENCY_GATEWAYGateway that support the requested currency is not configured.
400NO_GATEWAYS_AVAILABLENo gateway available.
400NO_TEST_CARD_IN_LIVE_MODEIn live mode, Test card can not used.
400NON_SUBSCRIPTION_PAYMENTUse onetime token or recurring token when create a charge.
400NOT_ONE_TIME_TOKENOther than onetime token is not supported.
400NOT_SUBSCRIPTION_TOKENUse subscription token or recurring token.
400PARTIAL_CAPTURE_NOT_SUPPORTEDPartial capture is not supported.
400QR_PROCESSING_DISABLEDQR code payment is disabled as payment type.
400RECURRING_TOKEN_DISABLEDThe transaction token is disabled. Or the account does not have permission to use recurring token.
400RECURRING_USAGE_LIMIT_REQUIREDusage_limit is required.
400RECURRING_USAGE_REQUIRES_CVVCVV is required.
400REFUND_EXCEEDS_CHARGE_AMOUNTRefund amount can not be larger than charge amount.
400REFUND_NOT_ALLOWEDThis payment type is not support refund. Or this refund has been refused.
400RESOURCE_LIMIT_REACHEDExceeded the resource limits.
400SUBSCRIPTION_ALREADY_ENDEDThe subscription is already finished.
400TOKEN_FOR_WRONG_STOREThe store of the transaction token is not the same as that of the subscription.
400TRANSACTION_ALREADY_PROCESSEDUsed transaction token can not be used.
400TRANSACTION_TOKEN_EXPIREDTransaction token expired.
400USAGE_LIMIT_NOT_APPLICABLEusage_limit is not applicable.
400VALIDATION_ERRORInvalid content of the request. Details are provided in the body error information
401AUTH_HEADER_MISSINGAuthorization header is missing.
401EXPIRED_LOGIN_TOKENLogin token expired.
401INVALID_APP_TOKENInvalid application token.
401INVALID_CREDENTIALSInvalid crendential for authentication.
401INVALID_DOMAINThe domain of Origin header is not in the allowed domains of the application token.
401INVALID_LOGIN_TOKENInvalid login token.
403CARD_LOCKEDThis card is temporarily locked because it exceeded the threshold of error count in a certain period.
Fail more than 5 times within 30 minutes, and we will put a 2-hour limit.
403INVALID_PERMISSIONSApplication token type is wrong. Or the account does not have permission.
403INSTALLMENT_PROCESSOR_INITIAL_AMOUNTS_NOT_SUPPORTEDGateway that support initial amount is not configured.
403OUTDATED_APP_TOKENThe version of application token is outdated. Please create a new application token.
403TEST_CARD_CANNOT_BE_BANNEDTest card can not be banned.
409IDEMPOTENCY_KEY_CONFLICTThe requested idempotency key is already used with other API or method.
409NON_UNIQUE_ACTIVE_TOKENActive transaction token must be unique.
409WEBHOOK_URL_EXISTSSpecified url is already registered.
500COULD_NOT_REFRESH_AUTHFailed to refresh login token, please contact support.
500DB_ERRORInternal database error, please contact support.
500FILE_UPLOAD_ERRORFailed to upload file, please contact support.
500IMPROPER_AUTHImproper authorization status, please contact support.
500TIMEOUTTimeout occurred in our internal processing, please contact support.
500UNABLE_TO_GET_IDEMPOTENT_RESULTThe request was not processed because the cache identified by Idempotency-Key was found, but the previous result could not be retrieved from the cache.
500UNKNOWN_ERRORUnexpected error occurred, please contact support.
503SERVICE_UNAVAILABLE_TRY_AGAINService is unavailable temporary. Retry the request later.

Detail reason of the error

Detail reason of the error specified reason field is defined in the below table:

ReasonDescription
CAPTURE_ONLY_FOR_CARD_PAYMENTAuthorization is only available when payment method is credit card.
CAPTURE_ONLY_FOR_CREDIT_CARDSAuthorization is only available when card type is credit card. Debit card and prepaid card can not be used for authorization.
CARD_LIMIT_EXCEEDED_FOR_STORETotal amount by credit card within a certain period exceeded the configured limit.
CHANGE_PROHIBITEDChange this field is prohibited.
CHARGE_AMOUNT_TOO_HIGHCharge amount is greater than the maximum charge amount.
CHARGE_AMOUNT_TOO_LOWCharge amount is lower than the minimum charge amount.
DEPRECATEDThis parameter is deprecated.
EXPIRATION_DATE_OUT_OF_BOUNDSExpiration is out of allowed range.
FORBIDDEN_PARAMETERPermission to use this parameter is not granted, or the requirement is not satisfied.
INSTALLMENT_ALREADY_SETSubscripiton is can not be change because it already started.
INSTALLMENT_INVALID_PLAN_TYPEInvalid installment plan type.
INVALID_AMOUNTAmount must be a number greater than 0.
INVALID_CARD_BRANDUnrecognized card brand.
INVALID_CARD_DESCRIPTORInvalid descriptor format.
INVALID_CARD_EXPIRATIONThe card expired.
REFUND_NOT_WITHIN_BOUNDSRefund amount is not between 1 to the charge amount inclusive.
INVALID_CARD_NUMBERInvalid card number format.
INVALID_CHARGE_STATUSInvalid charge status.
INVALID_CURRENCYUnrecognized currency.
INVALID_CVVCVV must be between 3 to 5 digits.
INVALID_FORMATInvalid format.
INVALID_FORMAT_COUNTRYUnrecognized country code.
INVALID_FORMAT_CURRENCYUnrecognized currency code.
INVALID_FORMAT_DOMAINInvalid domain format.
INVALID_FORMAT_EMAILInvalid email address format.
INVALID_LANGUAGEUnrecognized language code.
INVALID_PHONE_NUMBERInvalid phone number format.
INVALID_SCHEDULED_CAPTURE_DATECapture date must be after 1 hour from now and within 7 days.
INVALID_TIME_PERIODUnrecognized time period format.
MUST_BE_FUTURE_TIMEIt must be future time.
MUST_BE_LOWER_THAN_FULL_AMOUNTIt must be lower than the full amount.
MUST_BE_MONTH_BASED_TO_SETPeriod must be monthly.
NESTED_JSON_NOT_ALLOWEDNested JSON format is not supported.
NOT_SUPPORTED_BY_PROCESSORIt is not supported by the gateway.
ONLY_FOR_CARD_PAYMENTThis is available when the payment method is credit card.
ONLY_JAPANESE_PHONE_NUMBER_ALLOWEDOnly Japanese phone number is supported.
REQUIRED_VALUERequired value.

Payment errors

Resources that handle money such as charge or refund may return error information if they fail. Payment errors contains the following information:

  • code (number) – A unique key that can be used to match an error code.
  • message (string) – A short description of the error
  • detail (string) – A longer description if available of the error.

The codes are defined in the table below.

CodeDescription
301Invalid card number
302Invalid card expiration month
303Invalid card expiration year
304Card expired
305Invalid CVV
306Card rejected
307Invalid card
308Invalid card data
309Generic error, details will be included
310Invalid user data
311Too many charge requests for a single card within a short timespan
312Cancel operation is unavailable
313Charge expired (when capturing a charge)
314Seize card
315Contact card issuing bank
316Last name required
317Partial capture not supported
318Partial refund not supported
319Fraud suspected
320Error on the bank end of the transaction
321Dynamic descriptor is not supported
322The barcode/QR code is invalid
323The barcode/QR code is expired
324The barcode/QR code has already been used
325The barcode/QR code is currently in use
326Rejected due to exceeding high risk threshold
327Confirmation period has expired
328Revert failed. Manual intervention required.
329Refund failed
330Insufficient funds in customer wallet
331Invalid or missing metadata field value
332Cross border transaction not allowed: Missing identity card
333Cross border transaction not allowed: Missing phone number
334Cross border transaction not allowed: Unaccepted payment method
335Cross border transaction not allowed: Missing name
336Transaction limit exceeded for payment type
337Transaction limit exceeded for the merchant
338Transaction not found
339Duplicate transaction
340Payment wallet was rejected by the gateway
341Merchant is missing certain information required by the gateway
342Cross border transaction not allowed: Unaccepted currency
343Failed to process the payment due to a server error on the gateway
344The payment selected is temporarily unavailable from the gateway
345The payment was canceled
346Payment took too long to start processing due to internal system latency and was canceled. Please retry the payment.
355The selected payment type is not supported by the payment method

CodeDescription
500A preprocessing error occurred when attempting to execute the transaction. Please confirm that the correct inputs have been provided and refer to the error message for further details.
501An internal error has occurred. Please contact your support representative for follow up.
502The transaction was attempted but the payment provider did not respond in a timey manner and timed out. The charge will not be reattempted.

Customs declaration errors

The customs declaration resource may return error information if it fails. Custom declaration errors contains the following information:

  • code (number) – A unique key that can be used to match an error code.
  • message (string) – A short description of the error
  • detail (string) – A longer description if available of the error.

The codes are defined in the table below.

CodeDescription
601A system released error occurred on Univapay, see the details field for specific information.
602The payment processor rejected the submitted request, see the details field for specific information.
603The identity of the customer submitted was rejected by the customs authority.
604The required identity information of the customer was not submitted by the merchant.