Error responses

The Vitesse API uses HTTP status codes and structured JSON responses to explain why a request failed. The response format and available error codes depend on the operation.

The Vitesse API returns errors in two formats:

  • Operations for creating and managing payment requests and related resources return structured ProblemDetails responses. These responses include field-level validation errors when applicable.
  • Transaction, account movement, foreign exchange and cheque operations can return simple responses containing Code, Message and MoreInfo.

The common codes described below are not exhaustive. Check the API Reference for the response schemas and HTTP status codes defined for each operation.

Do not retry every failed request automatically. Use the HTTP status, error details and current resource status to determine whether to correct the request, request a new access token, retry later or contact Support.

Common HTTP status codes

StatusMeaningWhat to do
400 Bad RequestThe request is malformed, contains invalid values or fails request validation.Check the request path, parameters, headers and body. If the response contains an Errors array, correct each reported field.
401 UnauthorizedThe access token is missing, expired or invalid.

Check the Authorization header and if you are using the correct environment. If the access token has expired or is invalid, request a new token and send it using the Bearer authentication scheme.

Requesting another token with the same configuration will not resolve a missing role or resource assignment.

403 ForbiddenThe access token is valid, but the identity client does not have the access required for the operation.Check the scopes included in the token, the roles assigned to the identity client and its access to the relevant resources.
404 Not FoundThe requested resource does not exist or is not available to the identity client.Check the resource identifier and the identity client’s access to the resource.
409 ConflictThe request conflicts with the current state of a resource or with an existing resource.Check the returned error code and the current state of the affected resource. Resolve the conflict before sending the request again.
422 Unprocessable EntityThe request is valid, but Vitesse cannot process it because it violates a business rule.Use the response details to identify the violated rule, then correct the request or its prerequisite data.
429 Too Many RequestsYour application sent requests faster than the API allows within the permitted period.Reduce the request rate and wait before retrying. Follow the Retry-After header if the response includes one.
500 Internal Server ErrorVitesse encountered an unexpected error while processing the request.Retain the TraceId and contact Support if the problem continues. Do not repeatedly retry an operation that might create or change a resource.
❗

Do not retry a payment or another state-changing operation unless its documentation confirms that retrying is safe. An unsuccessful response does not always mean that Vitesse failed to receive or process the original request.

Problem details responses

Operations for creating and managing payment requests and related resources use a problem details response.

For example, a 401 Unauthorized response identifies the affected request path and explains why Vitesse rejected the request:

{
  "Type": "https://docs.vitessepsp.com/reference/errors",
  "Title": "Unauthorized",
  "Status": 401,
  "Instance": "/paymentRequests",
  "TraceId": "0HN3RP25B2NH6:00000001",
  "Detail": "You are not authorized to access this resource."
}

A problem details response can contain the following fields:

FieldDescription
TypeA URI that identifies the type of problem.
TitleA short summary of the error.
StatusThe HTTP status code returned for the request.
InstanceThe request path associated with the error.
TraceIdIdentifies the request. Retain this value when contacting Support.
DetailFurther information about the specific problem.
ErrorsValidation or business rule errors associated with the request.. Vitesse returns this field when applicable.

Not every response contains every field. For example, an authentication error might contain Detail but no Errors array.

Validation errors and business rule violations

When one or more request values fail validation or violate business rules, the response can contain an Errors array that identifies what you must correct:

{
  "Type": "https://docs.vitessepsp.com/reference/errors",
  "Title": "Bad request",
  "Status": 400,
  "Instance": "/paymentRequests",
  "TraceId": "0HN3LM4HTJSTI:00000001",
  "Detail": "One or more validation errors occurred.",
  "Errors": [
    {
      "Name": "Recipient.EmailAddress",
      "Reason": "Email address is not valid.",
      "Code": "PredicateValidator",
      "Severity": "Error"
    },
    {
      "Name": "Recipient.PhoneNumber",
      "Reason": "Phone number must use international format.",
      "Code": "PredicateValidator",
      "Severity": "Error"
    }
  ]
}

Each error entry can contain the following fields:

FieldDescription
NameThe request field associated with the error, when applicable.
ReasonAn explanation of why the Vitesse API rejected the field or request.
CodeA machine-readable identifier for the validator or business rule, when provided.
SeverityThe severity assigned to the error, when provided.

Use the Code, Reason and Detail values to determine what you must correct. Do not parse the human-readable wording to identify an error when the response provides a machine-readable Code.

The errors available for a particular operation depend on the resource and action. Check the operation’s API Reference entry and its supporting guide for operation-specific error codes and corrective actions.

Correct every reported problem before sending the request again. A single field can have more than one associated error.

Common error codes in problem details responses

The Vitesse API generally returns 400 Bad Request for a malformed or invalid request, and 422 Unprocessable Entity when a well-formed request violates a business rule.

The following table lists common Code values. Operations can return additional codes.

CodeMeaningWhat to do
PredicateValidatorA value failed a custom validation condition.
For example, Recipient.EmailAddress is amelia.example.com, which is not a valid email address.
The condition varies by field, so use Name and Reason to identify and correct the specific problem.
NotEmptyValidatorA required field is missing, null or empty.
For example, Recipient.Address.City is empty.
Use Name to identify the field and supply the correct value.
EmptyValidatorThe request supplied a field or object that must be omitted in the given circumstances.
For example, Recipient.BusinessDetails contains a value even though Recipient.Type is Person; business details apply only to business recipients.
Remove the field or object, or change the related field so that the supplied information is permitted.
RegularExpressionValidatorA value does not match the required format or permitted character pattern.
For example, RecipientReference is ORO-00000000-24-L0002200. The hyphens are not permitted because the field accepts only letters, numbers and spaces.
Change the value so that it follows the format described in Reason.
MaximumLengthValidatorA value contains more characters than the field permits.
For example, recipient.Address.AddressLine[0] contains 51 characters, but the field permits no more than 50.
Shorten the value to the maximum length specified in Reason.
NoMandatoryVerificationMethodsThe request does not contain the verification methods required for the operation. This will depend on customer configuration.
For example, recipients must enter a claim number before providing their payment details, but the claim number has not been configured as a mandatory verification method.
Configure at least one recipient verification method as mandatory. Contact Support if you cannot manage this configuration.
SortCodeA required sort code is missing or invalid. Use Reason for the precise failure.
For example, the request omits the sort code required for a UK bank account.
Supply a valid sort code in the field identified by Name.
DuplicateIdempotencyKeyThe request reuses an idempotency key with parameters that differ from those in the original request.
For example, the original request used the idempotency key for a payment of 100.00 GBP; a subsequent request uses the same key for 125.00 GBP.
Resend the original request unchanged, or use a new idempotency key for the changed request.

Simple error responses

Some operations return a simple error response containing Code, Message and MoreInfo.

{
  "Code": "ParsingError",
  "Message": "Error parsing the value 'abc' for the parameter 'SendValue'.",
  "MoreInfo": "https://docs.vitessepsp.com/reference/errors#parsingerror"
}
FieldDescription
CodeIdentifies the error condition. Use the Code to handle the error programmatically.
MessageDetails about this occurrence of the error. Use this information to diagnose the request, but do not write application logic that depends on the exact wording.
MoreInfoA link to guidance for the error code.

Find the returned Code in the tables below to understand the error and what to do.

💡

When troubleshooting, record Message, MoreInfo and any request or trace identifier.

Authentication and access errors

CodeMeaningWhat to do
TokenExpiredThe access token has expired.Request a new access token and resend the API request.
TokenInvalidThe access token is malformed or otherwise invalid.Request a new access token and send its complete value in the Authorization header.
TokenInvalidAudienceThe access token was not issued for the requested operation.Request a token using the identity client and access-token endpoint for the target environment.
TokenInvalidLifetimeThe token’s validity period is not acceptable.Request a new access token. If newly issued tokens continue to fail, retain the response details and contact Support.
TokenInvalidScopeThe access token does not contain a scope accepted by the operation.Request the scopes required for the operations your application uses. Ensure the identity client can use those scopes.
TokenInvalidSignatureVitesse could not verify the token signature.Request a new access token from the access-token endpoint for the target environment. Contact Support if the problem continues.
TokenIssuerInvalidThe service accepted by the target environment did not issue the access token.Request a token from the correct environment’s access-token endpoint.
TokenNotAllowedThe API does not permit the supplied token to access the merchant.Check that you are using the correct identity client and environment. Contact Support if the problem continues.
TokenRevokedThe access token or the credentials used to obtain it are no longer permitted.Request a new access token. If that fails, check the identity client in MAS or contact Support.
TokenTypeNotAcceptedThe API does not accept the supplied token type.Obtain an OAuth 2.0 bearer access token and use the Bearer authentication scheme.
UnauthorizedThe request does not contain a valid bearer access token.Check that the Authorization header is present, uses the Bearer scheme and contains a complete, unexpired access token.

Send an access token using the following header:

Authorization: Bearer <access-token>
❗

Do not paste an access token into a third-party website. If you need to inspect it, decode it locally without sharing or uploading it.

General request and resource errors

CodeMeaningWhat to do
CannotInstantiateComponentVitesse encountered an internal configuration or processing error.Retain the response details and contact Support.
HttpResponseExceptionVitesse encountered an internal error while processing an HTTP response.Retain the response details and contact Support.
InvalidMediaTypeThe operation does not support the request’s media type.Check the API Reference and set the Content-Type header required by the operation.
InvalidMerchantCodeVitesse could not resolve the merchant code.Retain the response details and contact Support.
InvalidStateChangeThe requested action is not permitted in the resource’s current state.Retrieve the resource, check its status and perform only an action permitted from that status.
MerchantDisabledThe merchant is disabled and cannot perform the operation.Contact Support.
MinMaxErrorThe minimum value in a transaction search range is greater than or equal to the maximum value.Provide a minimum value lower than the maximum. To search for an exact value, use the relevant exact-value filter.
MissingAssociatedAccountThe referenced account does not exist or is not available to the identity client.Check the account identifier and the identity client’s access.
ParsingErrorVitesse could not convert a request value to the type required by the operation.Use the accompanying message to identify the parameter, then provide the value in the format defined in the API Reference.
RateLimitExceededThe caller has exceeded a rate limit applied to the operation.Stop sending requests and retry later. Do not use a fixed retry interval unless the operation’s documentation defines one.
StoredRecipientNotFoundVitesse could not find the stored recipient identified in the request.Check that the identifier belongs to the stored-recipient resource used by the operation and that the identity client can access it.
UnclassifiedThe API could not classify the error under a more specific code.Retain the complete response, request or trace identifier and request time, then contact Support.

Payment and foreign exchange errors

CodeMeaningWhat to do
AmountAboveAccountLimitThe payment amount exceeds the upper payment limit configured for the source account.Reduce the amount or contact your account manager to review the account limit.

Additional context:
For example, Vitesse can reject a payment of 205.00 GBP when the applicable account limit is 100.00 USD. This code can also appear in TransactionFailureType as the downstream cause of a failed payment request.
ArgumentInvalidOne or more request values are invalid.Use the accompanying message or validation details to identify and correct each value.
ArgumentMustBeGreaterThanZeroA number in the request is zero or a negative value.Change the value named in the error to a number above zero.

Additional context:
For example, AccountId is 0, or SendValue is -10.
ArgumentNotProvidedThe request omits one or more required values.Use the accompanying message and the API Reference to identify and provide the missing values.
CalculatedReceiveValueIsZeroThe send amount is so small that the calculated receive amount rounds to zero.Increase the send amount.

Additional context:
Converting 0.01 PLN at a rate of 1 PLN = 0.208117 GBP produces 0.00208117 GBP, which rounds to 0.00 GBP.
CalculatedSendValueIsZeroThe receive amount is so small that the calculated send amount rounds to zero.Increase the receive amount.

Additional context:
Requesting 0.01 PLN from a GBP account at a rate of 1 PLN = 0.208117 GBP produces a send amount of 0.00208117 GBP, which rounds to 0.00 GBP.
DuplicateTransactionDetectedThe request matches another transaction under the duplicate-detection rules configured for the merchant.Determine whether the earlier transaction is the intended payment before submitting another request. Contact your account manager if you need to review the duplicate-detection rules.
DuplicateTransactionKeyThe value supplied in the TransactionKey header has already been used.Use the response details to identify the existing transaction and when Vitesse received it. Do not generate another key and resubmit until you have confirmed that doing so will not create a duplicate payment.
InsufficientBalanceThe source account does not have enough available balance to cover the transaction.Fund the account or reduce the amount. When Vitesse processes a payment request, check its status or webhook events because Vitesse can queue or reschedule some balance-related failures.
InsufficientFundingBalanceAt least one funding account associated with the transaction has insufficient available balance.Use the accompanying message to identify and fund the affected account. When Vitesse processes a payment request, check its status or webhook events because Vitesse can queue or reschedule some balance-related failures.
InvalidRateGroupThe supplied RateGroupId is invalid or has expired.Obtain a current rate group and resubmit the request.
MissingFeesVitesse could not resolve the fees required to process the request.Retain the response details and contact Support.
MissingForexRateVitesse could not resolve the foreign exchange rate required to process the request.Retain the response details and contact Support.
MissingMarginsVitesse could not resolve the margin required to process the request.Retain the response details and contact Support.
NoCurrencyAccountThe merchant does not have an account in the required source currency.Select an available source-currency account or contact Vitesse about the accounts available to the merchant.
OriginatorCountryRequiredThe originator address does not contain a valid ISO 3166-1 alpha-2 country code in the position required by the operation.Provide the originator address in the required format.
OriginatorRequiredVitesse requires originator information for the payment.Provide the ultimate debtor details when the merchant makes a payment on behalf of another party.
OutOfDateForexRateThe foreign exchange rate is no longer valid.Obtain a current rate and resubmit the request. Contact Support if the problem continues.
RequestedValueDateDisabledRequested value dates are not enabled for the merchant or selected currency.Omit the requested value date or contact your account manager.
RequestedValueDateTooDistantThe requested value date is later than the supported future date for the selected currency.Select an earlier date.
RequestedValueDateTooSoonThe requested value date does not allow enough processing time.Select a later date.
RequiresJSONAddressThe operation requires the recipient and originator addresses as structured JSON.Replace free-text addresses with the address objects defined for the operation.
UnsupportedCountryVitesse does not support the recipient country for the requested payment route.Select a supported country or payment route.
UnsupportedCurrencyVitesse does not support the recipient currency for the requested payment route.Select a supported currency or payment route.
UnsupportedRouteVitesse cannot route the payment using the requested currencies and payment details.Review the payment route and recipient details. Contact your account manager if you require a route that is not configured.

Account movement errors

CodeMeaningWhat to do
AccountMovementAboveOutOfHoursMaximumThe account movement exceeds the permitted out-of-hours value in GBP.Reduce the amount or submit the account movement during supported processing hours. Contact your account manager if you need to review the applicable limit.
AccountMovementAboveMaximumThe account movement exceeds the maximum value configured by Vitesse.Reduce the amount or contact your account manager to review the limit.
AccountMovementCreditAmountValueThe calculated credited amount is zero or negative. Vitesse calculates the credited amount by subtracting fees from the debit amount.Increase the debit amount or review the applicable fees. The credited amount must be greater than zero.
AccountMovementDisabledAccount movements are not enabled for the merchant.Contact your account manager to request access.
AccountMovementInsufficientBalanceThe source account does not have enough available balance to complete the account movement.Fund the account or reduce the amount before trying again.
AccountMovementManuallyCreatedThe account movement was created manually and cannot be changed through the API. The RequestFromApi value indicates how Vitesse created the account movement.Use the API to change only account movements for which RequestFromApi is true. Manage manually created account movements through Vitesse online.
CannotCreateAccountMovementVitesse could not create the account movement. A common cause is insufficient balance in the source account.Use the accompanying message to identify the cause. Fund the source account or correct the request as applicable.

Cheque and void errors

CodeMeaningWhat to do
ChequeFileCopyFileCopyNotAvailableVitesse has not prepared the cheque file copy yet.Try again later.
ChequeFileCopyFileCopyWasRemovedThe cheque file copy was removed and is no longer available.Contact Support if you still require the file.
ChequeFileCopyTransactionRouteTypeIsNotChequeThe transaction does not use a cheque route, so no cheque file copy is available.Check the transaction route before requesting the file.
ChequeFileCopyTransactionStatusFailedThe transaction failed, so no cheque file copy is available.Review the transaction failure instead.
ChequeFileCopyTransactionStatusPendingThe transaction is pending and the cheque file copy is not available yet.Check the transaction status and try again after processing completes.
ChequeNotSupportedVitesse does not support cheque payments for the specified recipient country and currency.Select another supported payment method or contact your account manager to discuss the route.
TransactionReturnAlreadyManagedByVitesseVitesse Operations is already managing a return or void request for the transaction.Do not create another request. Contact Support if you need an update.
VoidRequestAlreadyExistsAn active void request already exists for the transaction.Do not create another request. Retrieve or monitor the existing void request.
VoidRequestInvalidChequeStatusThe current cheque status does not permit a void request.Create a void request only when ChequeStatus is Uncashed.
VoidRequestInvalidDestinationCurrencyThe transaction’s destination currency is not supported for a void request.Use this operation only for eligible USD cheque transactions.
VoidRequestInvalidRouteTypeThe transaction does not use a route supported by the void operation.Use this operation only for eligible Cheque or PostalCheque transactions.
VoidRequestInvalidTransactionIdVitesse could not find the transaction, or the identity client cannot access it.Check the transaction request identifier and the identity client’s access.
VoidRequestInvalidTransactionStatusThe transaction is not in a status that permits a void request.Retrieve the transaction and confirm that its status is Succeeded before creating the request.
VoidRequestUnavailableVitesse encountered an internal error and could not create the void request.Retain the response details and contact Support.

Payment processing failures

Vitesse continues processing a payment asynchronously after creating it. A successful response to the create operation confirms that Vitesse accepted and created the payment request; it does not confirm that the payment completed successfully.

Some failures occur during this subsequent processing, so the original API response does not report the eventual failure. Check the payment request status or subscribe to payment request webhook events to determine the final outcome.

The PaymentRequestFailed event identifies a terminal failure:

{
  "EventType": "PaymentRequestFailed",
  "Data": {
    "PaymentRequestId": "0f132df8-a4e8-4c92-8970-4c69698e9d31",
    "MerchantId": "7d978f47-1907-4d5d-8f85-8f40a96d21c8",
    "FailedAt": "2026-09-21T10:30:00Z",
    "FailureReason": "TransactionFailed",
    "TransactionFailureType": "AmountAboveAccountLimit"
  }
}

FailureReason describes the general reason the payment request failed. When a downstream transaction exists and fails, TransactionFailureType can contain one of the coded transaction errors listed in the Simple error responses section.

Not every processing problem causes an immediate terminal failure. For example, Vitesse can retry or reschedule some balance-related failures. Use the payment request status and webhook event contract rather than assuming that every downstream error ends the payment request.

Handle unexpected errors

If Vitesse returns an unexpected error:

  1. Record the HTTP method and request path.
  2. Record the environment and approximate request time.
  3. Retain the HTTP status, error code and TraceId.
  4. Check whether Vitesse created or changed the requested resource before retrying.
  5. Contact Support if the problem continues.
❗

Do not send access tokens, identity client secrets or other credentials to Support.