API Response & 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.

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

Status Codes - Balanceless

Status Code	HTTP Code	Description
200	OK	Balances list retrieved successfully.
200	OK	Balance created successfully.
200	OK	Balances details retrieved successfully.
200	OK	Balance updated successfully.
200	OK	Successfully retrieved cards linked to the Balance.
200	OK	Successfully retrieved card details.
200	OK	Card updated successfully.
200	OK	The card details link was successfully generated.
200	OK	Transfer was successful.
200	OK	Successfully retrieved transactions.
201	Created	Card was created successfully.
204	No Content	Balance was successfully blocked. Blocking of cards linked to this Balance has been initiated.
204	No Content	Balance was successfully unblocked. Unblocking of cards linked to this Balance has been initiated.
204	No Content	Balance was successfully closed. Closing of cards linked to this Balance has been initiated.
204	No Content	The card was successfully blocked.
204	No Content	The card was successfully unblocked.
204	No Content	The card was successfully closed.
204	No Content	The Card details link was successfully deleted.
400	Bad Request	Bad Request. Refer to the Validation Error Codes Guide for a list of possible error codes.
401	Unauthorized	Unauthorized access, authentication required.
403	Forbidden	Forbidden, you don’t have permission to access this resource.
404	Not Found	Resource not found.
409	Conflict	Logical error. Refer to the relevant Error Codes Guide for details.
500	Internal Server Error	An internal server error occurred. Retry if retryable=true.

Error Codes and Descriptions for 409 response code:

Error	Description
AVAILABLE_BALANCE_MIN_GREATER_THAN_MAX	The provided minimum available balance is greater than the maximum.
CARD_CREATION_LIMIT_REACHED	The maximum number of card creations has been reached.
CARD_MODEL_NOT_ALLOWED	The card model is not supported by the provided card type.
CARD_TYPE_UNAVAILABLE	The card type provided is not available.
CLOSURE_END_DATE_BEFORE_START_DATE	Closure end date is before the start date.
CREATION_END_DATE_BEFORE_START_DATE	Creation end date is before the start date.
CURRENCY_NOT_ALLOWED	The selected currency is not permitted for this operation.
DESTINATION_INSTRUMENT_BLOCKED	Destination instrument is currently blocked.
DESTINATION_INSTRUMENT_NOT_FOUND	Destination instrument was not found.
DESTINATION_INSTRUMENT_TYPE_NOT_ALLOWED	Destination instrument type is not allowed.
DESTINATION_SAME_AS_SOURCE	Source and destination instruments cannot be the same.
END_DATE_BEFORE_START_DATE	End date is earlier than start date.
FOREX_NOT_SUPPORTED_FOR_TRANSACTION	Forex is not supported for this transaction.
INSTRUMENT_NOT_EMPTY	The instrument is not empty.
INSTRUMENT_STATE_INVALID	Invalid instrument state.
LINK_NOT_FOUND_OR_EXPIRED	No active or valid link found for the card reference.
MAX_DATE_RANGE_31_DAYS	Date range exceeds the maximum of 31 days.
NAME_NOT_UNIQUE	The provided name is not unique.
NOT_ENOUGH_FUNDS	Insufficient funds for the operation.
RANGE_START_DATE_OLDER_THAN_1_YEAR	Range start date is older than 1 year.
SOURCE_INSTRUMENT_BLOCKED	Source instrument is currently blocked.
SOURCE_INSTRUMENT_NOT_FOUND	Source instrument was not found.
SOURCE_INSTRUMENT_TYPE_NOT_ALLOWED	Source instrument type is not allowed.
SPEND_LIMIT_NOT_ALLOWED	The specified spend limit is not supported.
SPEND_LIMITS_NOT_AVAILABLE	Spend limits are not configured.
TOO_MANY_TRANSACTIONS	Transaction count has exceeded the allowed limit.
TRANSFER_AMOUNT_TOO_LARGE	The transfer amount exceeds the allowed limit.
TRANSFER_AMOUNT_TOO_SMALL	The transfer amount is below the allowed minimum.
TRANSFER_CURRENCY_DIFFERENT_FROM_SOURCE_AND_DESTINATION	Transfer currency differs from source or destination currency.
RANGE_START_DATE_OLDER_THAN_1_YEAR	Start date is older than one year.
CUSTOM_REFERENCE_NOT_UNIQUE	Custom reference provided is not unique.
UNKNOWN_ERROR	An unknown error occurred. Contact support.

Validation Errors

Validation Rules​

cardName parameter​

Authentication Errors

Virtual Card Factory Errors

Card and Fund Management Errors

Instrument Management Errors

Status Codes - Balanceless

Error Codes and Descriptions for 409 response code:​

Validation Rules

cardName parameter

Error Codes and Descriptions for 409 response code: