Generic Response & Error Codes

API Error Codes

The following is a list of errors that can be returned by any API method.

Status Code	Http Code	Description
Unauthorized	401	The input parameter security token was not specified or is invalid.
Forbidden	403	The IP invoking the API was not one of the allowed IPs.
Not Found	404	The request method was not found as the URL parameter was not specified in the URL.
Method Not Allowed	405	The URL parameter was not specified in the URL for the request method.
Unsupported Media Type	415	Server refused the request because the format is unsupported by the requested resource
Too Many Requests	429	The number of requests for this API has exceeded the maximum number of allowed requests.
System Error	500	A system error occurred in the Nium platform.
Service Unavailable	503	The system is temporarily unavailable.

API Validation Errors

When an API calls fails due to a validation error an error response will be returned, with the http status code reported as 400.

The error response is an "ErrorResponseWrapper" object representation similar to the one shown below. Note that the "response.details" property will specify which property failed validation (the CARD_REFERENCE in this case) and the type of validation failure (NOT_FOUND in this case)

{
    "envelope": {
        "statusCode": "VALIDATION_ERROR",
        "httpStatusCode": 400,
        "apiReference": "616b0389972d4f7a84e8f598a7643e82",
        "externalCallReference": null,
        "timestamp": 1669117138157
    },
    "response": {
        "details": {
            "CARD_REFERENCE": "NOT_FOUND"
        },
        "body": {}
    }
}

The types of validation failures are listed below.

Details	Description
NULL_OR_EMPTY	The input parameter was not specified.
NOT_FOUND	The input parameter did not identify an existing or valid entry.
INVALID_VALUE	The specified input parameter contained invalid characters, invalid values, or invalid formats.
INVALID_LENGTH	The length of the specified input parameter is invalid.
INVALID_CHARS	The specified input parameter is invalid due to invalid characters used.
NOT_UNIQUE	The specified input parameter must be unique across all entries of the same type.
INVALID_STATE	The input parameter virtual card factory name did not identify a virtual card factory in an active state.
INVALID_FORMAT	The specified input parameter was not in a valid format

API Validation Rules

These are valid characters corresponding to parameters within the Nium API.

cardName parameter

The card name parameter must follow these rules

• a to z
• A to Z
• 0 to 9
• Dash (-), dot (.), underscore (_), forward slash (/), space ( )
• \u00A1 to \u00FF (Latin-1)
• \u0100 to \u017F (Latin Extended A)
• \u0180 to \u024F (Latin Extended B)
• \u4e00 to \u9fff (Unified CJK Ideographs)
• \u0400 to \u04FF (Cyrillic)
• \u0500 to \u0527 (Cyrillic Supplement)
• \u2DE0 to \u2DFF (Cyrillic Extended A)
• \uA640 to \uA673 and \uA67C to \uA697 (Cyrillic Extended B)

API Authentication Errors

When an API calls fails due to an authentication error an error response will be returned, with the http status code reported as 409 in certain instances.

The error response is an "ErrorResponseWrapper" object representation similar to the one shown below. Note that the "response.details" property will specify the type of authentication error.

{
    "envelope": {
        "statusCode": "LOGICAL_ERROR",
        "httpStatusCode": 409,
        "apiReference": "616b0389972d4f7a84e8f598a7643e82",
        "externalCallReference": null,
        "timestamp": 1669117138157
    },
    "response": {
        "details": {
            "TOO_MANY_FAILED_ATTEMPTS": ""
        },
        "body": {}
    }
}

The types of authentication failures handled in the manner described above are listed below.

Details	Description
TOO_MANY_FAILED_ATTEMPTS	The maximum number of failed login attempts has been exceeded.
LEGISLATION_RESTRICTED	The login failed due to legislation restrictions.
COUNTRY_NOT_ALLOWED	The specified country is not allowed for login.

API Virtual Card Factory Errors

When an API calls fails due to a virtual card factory (card type) error an error response will be returned, with the http status code reported as 409.

The error response is an "ErrorResponseWrapper" object representation similar to the one shown below. Note that the "response.details" property will specify the type of failure.

{
    "envelope": {
        "statusCode": "LOGICAL_ERROR",
        "httpStatusCode": 409,
        "apiReference": "616b0389972d4f7a84e8f598a7643e82",
        "externalCallReference": null,
        "timestamp": 1669117138157
    },
    "response": {
        "details": {
            "LOW_ATV_USED": ""
        },
        "body": {}
    }
}

The types of card factory failures are listed below.

Details	Description
LOW_ATV_USED	No available configurations due to low average transaction value.
NO_MATCHING_CONFIG	No matching factory configuration was found.

API Card and Fund Management Errors

When an API calls fails due to card or fund management errors an error response will be returned, with the http status code reported as 409.

These are error that can be returned during any process that involves fund movement or a
change in the state of a card.

The error response is an "ErrorResponseWrapper" object representation similar to the one shown below. Note that the "response.details" property will specify the type of failure.

{
    "envelope": {
        "statusCode": "LOGICAL_ERROR",
        "httpStatusCode": 409,
        "apiReference": "616b0389972d4f7a84e8f598a7643e82",
        "externalCallReference": null,
        "timestamp": 1669117138157
    },
    "response": {
        "details": {
            "NOT_ENOUGH_FUNDS": ""
        },
        "body": {}
    }
}

The types of card or fund management failures are listed below.

Details	Description
AUTHENTICATION_DATA_NOT_SUPPORTED	The handling of authentication data for virtual cards is not supported by the card provider.
CANCELLATION_NOT_ALLOWED	The scheduled load cannot be cancelled since the instruction has been completed. In other words, the clearance date is in the past.
CARD_ALREADY_EXPIRED	The chosen card is already expired.
CARD_DELETION_FAILED	The virtual card deletion failed.
CARD_IMAGE_NOT_FOUND	The getCardImages parameter is true and one or both of the card images were not found.
CARD_STATE_INVALID	The virtual card identified with the input card reference was not active.
CLEARANCE_DATE_AFTER_MAXIMUM_CLEARANCE_DATE	The clearance date cannot be a date greater than the maximum clearance date of a card.
CLEARANCE_DATE_BEFORE_A_SCHEDULED_LOAD	A clearance date must be later than all scheduled loads on a card.
CLEARANCE_DATE_IN_THE_PAST	The clearance date cannot be a date less than today or a date greater than the expiry date.
CURRENCY_NOT_ALLOWED_FOR_TRANSACTION	The action is not allowed between the input cross-currencies.
DESTINATION_INSTRUMENT_ALREADY_FUNDED	The instrument being funded has been configured as a single fund instrument and hence reloading is not allowed.
EXTENSION_UNSUPPORTED	Extension of expiry date is not supported by the virtual card factory of this card.
FACTORY_UNAVAILABLE	The input parameter instrument factory name did not identify a valid instrument factory.
INVALID_ISSUER	The specified source and destination must have the same issuer. Note that transfers between different issuers are allowed only when both the source and destination are funding accounts.
ISSUING_LIMIT_EXCEEDED	The issuing capacity limit for the respective issuer and currency was reached.
LOAD_ALREADY_PROCESSED	The update of the scheduled load fails if the schedule date is in the past and parameters like funding account reference, amount and schedule date are being updated. The reason is that the load transaction has already been processed and changes cannot occur.
MINIMUM_AVAILABLE_BALANCE_EXCEEDED	The minimum available balance threshold of the instrument was exceeded by the transaction.
NEW_EXPIRY_DATE_IS_BEFORE_CURRENT	The new expiry date is earlier than the current one.
NOT_ENOUGH_FUNDS	The specified source instrument of the transaction does not have enough funds.
SCHEDULED_LOAD_DATE_AFTER_CLEARANCE_DATE	A scheduled load can happen before the clearance date of the card (even on the same day).
TIME_FRAME_GREATER_ONE_YEAR	The period between input parameter start date and input parameter end date was greater than one year.
TRANSFER_AMOUNT_TOO_LARGE	The specified amount is too large.
TRANSFER_AMOUNT_TOO_SMALL	The specified amount is too small.

API Instrument Management Errors

When an API calls fails due to instrument management errors an error response will be returned, with the http status code reported as 409.

These are error that can be returned during any process that involves instrument management.

The error response is an "ErrorResponseWrapper" object representation similar to the one shown below. Note that the "response.details" property will specify the type of failure.

{
    "envelope": {
        "statusCode": "LOGICAL_ERROR",
        "httpStatusCode": 409,
        "apiReference": "616b0389972d4f7a84e8f598a7643e82",
        "externalCallReference": null,
        "timestamp": 1669117138157
    },
    "response": {
        "details": {
            "KEY": "VALUE"
        },
        "body": {}
    }
}

Reason Description

Reason Description	Description
APPROVED	Transaction approved.
REFER_TO_ISSUER	Refer the cardholder to the issuer for further instructions.
INVALID_MERCHANT	Merchant is invalid or not permitted to process the transaction.
CAPTURE_CARD	Card should be retained by the acceptor.
DENIED	Transaction declined by the issuer or due to an issuer-defined error.
INVALID_TRANSACTION	Invalid transaction type or request.
INVALID_AMOUNT	Invalid transaction amount.
INVALID_CARD	Invalid card number.
UNABLE_TO_ROUTE_TRANSACTION	Unable to route the transaction to the issuer or appropriate processing endpoint.
CUSTOMER_CANCELLATION	Transaction cancelled by the cardholder.
FORMAT_ERROR	Message format is invalid.
EXPIRED_CARD_PICKUP	Card has expired and should be retained.
EXPIRED_CARD	Card has expired.
CARD_LOST_PICKUP	Card has been reported lost and should be retained.
CARD_STOLEN_PICKUP	Card has been reported stolen and should be retained.
ACCOUNT_CLOSED	The account associated with the card is closed.
INSUFFICIENT_FUNDS	Insufficient funds or credit available to complete the transaction.
INVALID_PIN	The PIN entered is incorrect.
TRANSACTION_NOT_ALLOWED_TO_CARDHOLDER	The transaction is not permitted for this cardholder.
TRANSACTION_NOT_ALLOWED_TO_TERMINAL	The transaction is not permitted at this terminal or merchant.
TRANSACTION_NOT_SUPPORTED_BY_ISSUER	The issuer does not support this transaction type.
AMOUNTS_LIMITS_EXCEEDED	The transaction amount exceeds the permitted limit.
RESTRICTED_CARD	The card is restricted from performing this transaction.
SECURITY_ERROR	A security validation or verification error occurred.
FREQUENCY_LIMITS_EXCEEDED	The transaction frequency limit has been exceeded.
RESPONSE_TIMEOUT	The issuer did not respond within the expected time.
CARDHOLDER_CONTACT_ISSUER	The cardholder should contact the card issuer for further assistance.
PIN_NOT_CHANGED	The requested PIN change was unsuccessful.
PIN_TRIES_EXCEEDED	The maximum number of PIN retry attempts has been exceeded.
INVALID_ISSUER	The issuer could not be identified or is invalid.
ACCOUNT_BALANCE_UNAVAILABLE	The account balance is currently unavailable.
UNNACCEPTABLE_PIN	The PIN does not meet the issuer's security requirements.
TRANSACTION_NOT_ALLOWED	This transaction type is not permitted.
TIMEOUT_AT_IEM	The transaction timed out while communicating with the issuer endpoint.
NO_CASHBACK_ALLOWED	Cashback is not permitted for this transaction.
CRYPTOGRAPHIC_FAILURE	Cryptographic validation failed.
AUTHENTICATION_FAILURE	Authentication failed.
ISSUER_OR_SWITCH_INOPERATIVE	The issuer or payment switch is temporarily unavailable.
DUPLICATE_TRANSACTION	A duplicate transaction was detected.
SYSTEM_MALFUNCTION	A system error prevented the transaction from being processed.
VERIFICATION_DATA_FAILED	Verification data provided with the transaction failed validation.
SCA_REQUIRED_CARD_FORM_FACTOR	Strong Customer Authentication (SCA) is required using a card form factor.
SCA_REQUIRED_NON_CARD_FORM_FACTOR	Strong Customer Authentication (SCA) is required using a non-card form factor.
DECLINE_CVV2_FAILURE	The transaction was declined because CVV2 verification failed.