General Errors

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.

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

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)

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.

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.

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
NOT_ENOUGH_FUNDS	The specified source instrument of the transaction does not have enough funds.
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.
CURRENCY_NOT_ALLOWED_FOR_TRANSACTION	The action is not allowed between the input cross-currencies.
TRANSFER_AMOUNT_TOO_SMALL	The specified amount is too small.
TRANSFER_AMOUNT_TOO_LARGE	The specified amount is too large.
DESTINATION_INSTRUMENT_ALREADY_FUNDED	The instrument being funded has been configured as a single fund instrument and hence reloading is not allowed.
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.
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.
CLEARANCE_DATE_IN_THE_PAST	The clearance date cannot be a date less than today or a date greater than the expiry date.
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.
SCHEDULED_LOAD_DATE_AFTER_CLEARANCE_DATE	A scheduled load can happen before the clearance date of the card (even on the same day).
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.
CARD_DELETION_FAILED	The virtual card deletion failed.
TIME_FRAME_GREATER_ONE_YEAR	The period between input parameter start date and input parameter end date was greater than one year.
FACTORY_UNAVAILABLE	The input parameter instrument factory name did not identify a valid instrument factory.
NEW_EXPIRY_DATE_IS_BEFORE_CURRENT	The new expiry date is earlier than the current one.
CARD_ALREADY_EXPIRED	The chosen card is already expired.
EXTENSION_UNSUPPORTED	Extension of expiry date is not supported by the virtual card factory of this card.
AUTHENTICATION_DATA_NOT_SUPPORTED	The handling of authentication data for virtual cards is not supported by the card provider.
MINIMUM_AVAILABLE_BALANCE_EXCEEDED	The minimum available balance threshold of the instrument was exceeded by the transaction.

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": {}
    }
}