Error codes

As this is an HTTP API, success or failure of requests can be determined by the HTTP status code of the response.

• Requests that succeed will return a 2xx success class code.
• Requests that fail will return a 4xx client error class code or (infrequently) a 5xx server error class code.

If a request fails, in addition to the HTTP status code our API provides as much additional information as possible in the response (as JSON) to indicate the reason(s) for the error.

GET api/transactions/search?SendValue=aaaaa

HTTP 400 - Bad Request
{
    "Code": "ParsingError",
    "Message": "Error parsing the value 'aaa' for the parameter 'SendValue'",
    "MoreInfo": "https://docs.vitessepsp.com/v2.16/refs/errors#section-ParsingError"
}

A full list of our API error codes is below:

AccountMovementAboveOutOfHoursMaximum

The account movement is above the maximum value in GBP that we permit for "out of hours" account movements. This period is typically 4pm Friday to 8am Monday in the UK.

AccountMovementAboveMaximum

The account movement is above the maximum value in GBP that we have configured in our system. If required, contact your account manager to review this limit.

AccountMovementCreditAmountValue

The credited amount for an account movement is calculated as:

Credited Amount = Debit Amount − Fees

The credited amount must always be greater than zero. If the fees exceed or equal the debit amount, the resulting credited amount will be zero or negative, which is invalid.

AccountMovementDisabled

Moving money between accounts in the API is a new feature and is not accessible to all merchants. If you call the API and receive this error, contact your account manager to ask if account movements can be enabled for your account.

AccountMovementInsufficientBalance

The specified 'send currency' or 'send account' has insufficient funds to cover the account movement.

AccountMovementManuallyCreated

Account movements can be created in the API but also manually by end users. When using the API you can only change account movements that have been created via the API - and vice versa. Although all account movements are visible in MAS, users can only take action on those created manually.

This error indicates that the account movement you attempted to update was created manually. Each account movement includes a RequestFromApi flag, which is set to true only when the account movement was created via the API.

AmountAboveAccountLimit

Each merchant account in the system can have an upper limit associated with it. Any individual transaction request above this limit will raise this error.

As an example, if the limit on an account was 100,000 GBP, sending in a transaction request above this limit would result in the following error message being returned from the API...

HTTP 400 - Bad Request
{
	"Code": "AmountAboveAccountLimit",
	"Message": "The transaction amount of 205.00 GBP is above the account limit of 100.00 USD. The transaction will not be processed.",
	"MoreInfo": "https://docs.vitessepsp.com/reference/errors#amountaboveaccountlimit"
}

Account limits can only be set by our operations staff - if you would like limits enforced, contact your account manager.

APIKeysDeprecated

The previous API key system has been deprecated and now disabled. Refer to Authentication to create tokens that can be used to access the Vitesse API.

ArgumentInvalid

This response indicates that one or more arguments passed to the API have an invalid value.

ArgumentMustBeGreaterThanZero

When creating a tranasction request, the SendValue or ReceiveValue must be specified as positive numbers.

ArgumentNotProvided

One or more mandatory arguments have not been passed to the API.

CalculatedReceiveValueIsZero

When calling the API and specifying a small Send value, this error can be thrown if the calculated Receive value is zero. As an example, if you wished to Send 0.01 PLN to GBP, with an exchange rate of 0.208117, then the GBP value would be 0.00208117 which when rounded would be zero. Specify a larger Send value.

CalculatedSendValueIsZero

When calling the API and specifying a very small receive value, this error can be thrown if the calculated send value is zero. As an example, if you wished to receive 0.01 PLN from GBP, with an exchange rate of 1 PLN = 0.208117 GBP, then the GBP amount would be 0.00208117 which when rounded would be zero. Specify a larger Receive value.

CannotCreateAccountMovement

The account movement cannot be created. The error returned will provide further details of the error, which is most likely to be that the source account does not hold sufficient funds.

CannotInstantiateComponent (*)

This is an internal error and if you receive it, contact Support.

ChequeFileCopyFileCopyNotAvailable

The Cheque File Copy cannot be retrieved because the cheque file copy has not yet been prepared.

ChequeFileCopyFileCopyWasRemoved

The Cheque File Copy cannot be retrieved because the cheque file copy was removed.

ChequeFileCopyTransactionRouteTypeIsNotCheque

The Transaction for which you have requested a cheque file copy is not a Cheque, so no file is available.

ChequeFileCopyTransactionStatusFailed

The Transaction for which you have requested a cheque file copy is in the Failed state, so no file is available.

ChequeFileCopyTransactionStatusPending

The Transaction for which you have requested a cheque file copy is in the Pending state, so no file is available.

ChequeNotSupported

Cheque payments to the provided Recipient Country and Recipient Currency are not currently supported. Contact your account manager if you wish you payout by cheque on this route.

DeferredTransactionAlreadyExpired

When grouping deferred transactions you can choose one or more transactions to group together. This indicates that at least one of the desired transaction has already expired and so can no longer be used.

DifferentGroupCountries

When grouping deferred transactions, all transactions must be for merchants assigned to the same country. We have "linked accounts", where it's possible to link one merchant to zero or more other merchants in a type of parent-child relationship, such that the parent merchant can use child accounts when making payments. If the child merchant and parent merchant are not setup as the same country, then this error wil lbe returned when attempting to group transactions that span both merchants.

DifferentGroupCurrencies

When grouping deferred transactions, all transactions must be of the same currency. If more than one currency is found in the group then this error will be reported.

DuplicateTransactionDetected

If duplicate transaction checking has been setup for your merchant account, this error indicates that the request matches another request already in the system.

This option is not enabled by default, if you wish us to handle duplicate checking, contact your account manager who can discuss the options with you.

DuplicateTransactionKey

This error is returned from the system when you have used the TransactionKey header when calling the API, and the value used has been used sometime before. When this error is returned by the API. we will also include details of the other transaction where this value was used, and the datestamp of that transaction to aid in your debugging.

HttpResponseException

An HTTP Response Exception was thrown whilst processing the error. Contact Support.

InsufficientBalance

Indicates that the specified 'send currency' or 'send account' has insufficient funds to cover the transaction.

InsufficientFundingBalance

This indicates that at least one Funding account for your transaction has an insufficient balance. The error message will provide details of the account, and we log this information internally too for followup purposes.

InvalidApiKey

The API Key passed to the API is missing or invalid.

API keys have been replaced by API Tokens, so it is unlikely that you will receive this error

InvalidGroupingRequest

When grouping deferred transactions an invalid request was made. Most typically this is using a transaction ID that is not a deferred transaction, or that has already been grouped.

InvalidStateChange

When changing the state of a resource you may receive this error as the state change cannot be completed. As an example, you might be trying to cancel an account movement request that has already been completed.

InvalidRateGroup

When calling the API with a RateGroupId, this error indicates that the rate group is invalid or has expired.

InvalidMediaType

The API only accepts application/json as a media type header. Any other option will result in this error code.

InvalidMerchantCode (*)

Contact Support.

MerchantDisabled

The associated merchant has been disabled. Contact Support.

MinMaxError

When specifying a range of possible values in a transaction search, the minimum value of the range must be less than the maximum value of the range. The minimum and maximum also cannot be equal; if you need to specify an exact value, you don't need to use a range in your search.

MissingAssociatedAccount

An account in the system does not exist or you do not have access to it.

MissingFees (*)

Contact Support.

MissingForexRate (*)

Contact Support.

MissingMargins (*)

Contact Support.

MustBeSameSendAccountWhenDDFunded

When calling the deferred transaction grouping API, we check each transaction to lookup its send account, and from that we then check if this account can be funded by direct debit. If there's a mix of direct debit and non direct debit funded tranasctions in the group, this error will be returned from the API.

NoCurrencyAccount

You do not have an account for the specified currency. Merchants can hold multiple currency accounts, but when sending money from the Vitesse system, you must have an account in the "source" currency.

NoDeferredMargin (*)

Contact Support.

OriginatorCountryRequired

The last two characters of the originator address field must be a valid ISO 3166-1 two letter country code.

OriginatorRequired

The Originator field was omitted from the request. Originator (ultimate debtor) information is required as part of the transaction information for fourth-party payments - those where the merchant is sending money on behalf of someone else - after the second set of EU Wire Transfer Regulations (WTR2) came into effect on the 26th June 2017.

OutOfDateForexRate (*)

Contact Support.

ParsingError

This indicates that the value given for an API request parameter was in the incorrect format - for example, you'll receive this error if you try to provide non-numeric data in a field expecting a numeric value or amount.

RateLimitExceeded

Some parts of our API are rate limited to avoid overuse. This error occurs if a rate limit has been exceeded.

RequestedValueDateDisabled

The Requested Value Date feature is disabled for your merchant account or for the selected currency. Contact your account manager for assistance.

RequestedValueDateTooDistant

The system only supports a discrete number of days for future value date requests. Your request falls outside the allowable number of days for the selected currency.

RequestedValueDateTooSoon

This indicates that the requested value date cannot be achieved as it is too close to the current date fo us to be able to process the transaction in time.

RequiresJSONAddress

Provide Recipient and Originator addresses in JSON format.

StoredRecipientNotFound

This indicates that the stored recipient corresponding to the stored recipient ID provided in the API request was not found - check you are providing the correct ID.

TokenExpired

The authentication token sent to the API has expired. A new one will need to be generated in the Merchant Administration System.

TokenInvalid

The authentication token sent to the API is invalid. Ensure the token was copied correctly from the Merchant Administration System.

Common problems are not copying the first or last character of the token. You can also check the token online by pasting it into https://jwt.io. This will attempt to de-construct the token, and if it fails to read the token then it's safe to assume that the token is indeed incorrect.

TokenInvalidAudience

This indicates that the Audience claim within the token is invalid.

TokenInvalidLifetime

Indicates that the authentication token lifetime (i.e. start and end dates) are invalid in some way.

TokenInvalidScope

Indicates that the authentication token's scope is incorrect. Only scope of API is supported.

TokenInvalidSignature

This indicates that the signature section of the token is incorrect.

TokenIssuerInvalid

This indicates that the token may not have been issued for this system.

TokenNotAllowed

This indicates that the authentication token is not allowed.

This occurs when a token is valid but the setting to allow Vitesse Identity Provider tokens was disabled for the Merchant.

TokenRevoked

This error is displayed when a token has been manually revoked in the system.

Tokens have a defined lifetime (typically one year) but can be manually revoked, which is useful in the case where a token has become compromised, or if you simply want to expire a token early for some reason.

TokenTypeNotAccepted

This indicates that the type of authentication token is currently not accepted.

TransactionReturnAlreadyManagedByVitesse

This indicates that a void request could not be created as Vitesse Operations are already managing either a return or void request for the given transaction.

Unauthorized

You will receive this error when the API request contains an invalid or missing token in the Authorization header. This error always indicates an issue with how the API request has been constructed.

This is the most common error during integration. Typical causes include:

• No token included in the request
• The word “Bearer” is missing from the Authorization header
• The supplied token does not contain the required role for the endpoint

Each API endpoint is secured by a specific role, and each token contains one or more roles. If the token does not include the correct role, an Unauthorized response is returned.

Unclassified (*)

A general code if none of the other error codes fit. Note the error number that is returned and contact customer support.

UnsupportedCountry

The country you are attempting to use to payout is currently not supported.

UnsupportedCurrency

The currency you are attempting to pay out to is currently not supported.

UnsupportedRoute

We have no route to send currency X to currency Y.

VoidRequestAlreadyExists

A new void request can not be created as an active void request already exists for the given transaction.

VoidRequestInvalidChequeStatus

A new void request can not be created as the transaction's ChequeStatus is not Cashed

VoidRequestInvalidDestinationCurrency

A new void request can not be created as the given transaction's destination currency is not USD.

VoidRequestInvalidRouteType

A new void request can not be created as the given transaction's route type is not either Cheque or PostalCheque.

VoidRequestInvalidTransactionId

A transaction with the given TransactionRequestId does not exist or your API key does not have the necessary permission to access it. As such, void request details can not be retrieved and/or a new void request can not created for the transaction.

VoidRequestInvalidTransactionStatus

A new void request can not be created as the given transaction's status is not Succeeded.

VoidRequestUnavailable (*)

An internal error has prevented a new void request from being created.