Error Codes Guide

General Errors

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

Status CodeHttp CodeDescription
Unauthorized401The input parameter security token was not specified or is invalid.
Forbidden403The IP invoking the API was not one of the allowed IPs.
Not Found404The request method was not found as the URL parameter was not specified in the URL.
Method Not Allowed405The URL parameter was not specified in the URL for the request method.
Unsupported Media Type415Server refused the request because the format is unsupported by the requested resource
Too Many Requests429The number of requests for this API has exceeded the maximum number of allowed requests.
System Error500A system error occurred in the Nium platform.
Service Unavailable503The 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.

DetailsDescription
NULL_OR_EMPTYThe input parameter was not specified.
NOT_FOUNDThe input parameter did not identify an existing or valid entry.
INVALID_VALUEThe specified input parameter contained invalid characters, invalid values, or invalid formats.
INVALID_LENGTHThe length of the specified input parameter is invalid.
INVALID_CHARSThe specified input parameter is invalid due to invalid characters used.
NOT_UNIQUEThe specified input parameter must be unique across all entries of the same type.
INVALID_STATEThe input parameter virtual card factory name did not identify a virtual card factory in an active state.
INVALID_FORMATThe 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.

DetailsDescription
TOO_MANY_FAILED_ATTEMPTSThe maximum number of failed login attempts has been exceeded.
LEGISLATION_RESTRICTEDThe login failed due to legislation restrictions.
COUNTRY_NOT_ALLOWEDThe 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.

DetailsDescription
LOW_ATV_USEDNo available configurations due to low average transaction value.
NO_MATCHING_CONFIGNo 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.

DetailsDescription
NOT_ENOUGH_FUNDSThe specified source instrument of the transaction does not have enough funds.
INVALID_ISSUERThe 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_EXCEEDEDThe issuing capacity limit for the respective issuer and currency was reached.
CURRENCY_NOT_ALLOWED_FOR_TRANSACTIONThe action is not allowed between the input cross-currencies.
TRANSFER_AMOUNT_TOO_SMALLThe specified amount is too small.
TRANSFER_AMOUNT_TOO_LARGEThe specified amount is too large.
DESTINATION_INSTRUMENT_ALREADY_FUNDEDThe instrument being funded has been configured as a single fund instrument and hence reloading is not allowed.
LOAD_ALREADY_PROCESSEDThe 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_ALLOWEDThe 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_PASTThe clearance date cannot be a date less than today or a date greater than the expiry date.
CLEARANCE_DATE_AFTER_MAXIMUM_CLEARANCE_DATEThe clearance date cannot be a date greater than the maximum clearance date of a card.
CLEARANCE_DATE_BEFORE_A_SCHEDULED_LOADA clearance date must be later than all scheduled loads on a card.
SCHEDULED_LOAD_DATE_AFTER_CLEARANCE_DATEA scheduled load can happen before the clearance date of the card (even on the same day).
CARD_IMAGE_NOT_FOUNDThe getCardImages parameter is true and one or both of the card images were not found.
CARD_STATE_INVALIDThe virtual card identified with the input card reference was not active.
CARD_DELETION_FAILEDThe virtual card deletion failed.
TIME_FRAME_GREATER_ONE_YEARThe period between input parameter start date and input parameter end date was greater than one year.
FACTORY_UNAVAILABLEThe input parameter instrument factory name did not identify a valid instrument factory.
NEW_EXPIRY_DATE_IS_BEFORE_CURRENTThe new expiry date is earlier than the current one.
CARD_ALREADY_EXPIREDThe chosen card is already expired.
EXTENSION_UNSUPPORTEDExtension of expiry date is not supported by the virtual card factory of this card.
AUTHENTICATION_DATA_NOT_SUPPORTEDThe handling of authentication data for virtual cards is not supported by the card provider.
MINIMUM_AVAILABLE_BALANCE_EXCEEDEDThe 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": {}
    }
}