Skip to main content

Errors

When a request fails, the API returns an HTTP error status and a structured response with one or more errors in data.errors.

Error response​

{
"status": "error",
"data": {
"errors": [
{
"errorMessage": "resourceNotFound",
"errorType": "GENERAL",
"errorId": "3f69d9b6",
"errorDescription": "Resource not found",
"errorField": null,
"params": [],
"requestParams": {}
}
]
}
}
FieldDescription
errorMessageMachine-readable error code. Use it in your error handling.
errorTypeError category: FIELD (one field is invalid, see errorField), FORM (the request as a whole), or GENERAL.
errorIdIdentifier of this error. Log it and include it in requests to support.
errorDescriptionHuman-readable description. Do not use it in program logic: the text may change.
errorFieldThe request field related to the error, if any.
paramsAdditional parameters of the error, if any.
requestParamsRequest parameters related to the error, if any.

Common error codes​

The list below covers the codes an integration usually needs to handle. It is not complete: a method can return other codes. Treat an unknown errorMessage as a general error, and log its errorId.

errorMessageWhat it means
missingRequestParameterA required parameter is missing.
methodArgumentTypeMismatchA parameter has the wrong type, for example text instead of a number.
httpMessageNotReadableThe request body is not valid JSON or does not match the expected structure.
unrecognizedFieldThe request body contains a field the method does not accept.
badParametersExceptionOne or more parameters are invalid.
badFormatAmountExceptionThe amount has an invalid format.
notEnoughMoneyExceptionThe source wallet does not have enough funds.
limitPerTransactionExceptionThe amount exceeds the limit for one transaction.
limitPerMonthExceptionThe transaction exceeds the monthly limit.
walletDoesNotExistThe wallet in the request does not exist.
walletCurrencyIncorrectExceptionThe wallet currency does not match the request.
recipientDoesNotExistExceptionThe recipient account does not exist.
paymentMethodNotAvailableForMerchantApiThe payment method is not available for your API.
resourceNotFoundThe endpoint does not exist.
attemptsHaveEndedExceptionThe account has used up its hourly request limit. See Request limits.
tryAgainAfterAWhileThe data is temporarily locked. Retry later.
serviceTemporaryUnavailableA service is temporarily unavailable. Retry later.
internalServerErrorUnexpected server error.

HTTP status codes​

StatusMeaning
400The request is malformed, contains invalid parameters, or cannot be processed. Also returned when an order or other entity is not found.
401Authentication headers are missing or invalid, or the account has used up its hourly request limit (attemptsHaveEndedException).
404The requested endpoint was not found.
405The endpoint does not support this HTTP method (httpMethodNotAllowed).
409The data is temporarily locked (tryAgainAfterAWhile).
415The Content-Type of the request is not supported (unknownContentType).
500Unexpected server error (internalServerError).
503A service is temporarily unavailable (serviceTemporaryUnavailable).

Do not derive an error code from the HTTP status alone: the same status can carry different errorMessage values.

Handle errors​

  • Log errorId for every error.
  • Check errorField to find the field to correct.
  • After 401, check the API name, the account email, the token, and the server time in UTC.
  • If the API has no permission for the operation or your server is not allowed to call it, check the permissions of the API and its IP whitelist in Payment Tools.

Retry safely​

Errors fall into two groups:

  • Temporary — 409 (tryAgainAfterAWhile), 503 (serviceTemporaryUnavailable), and timeouts. Retry read and validation requests with a growing delay between attempts. For requests that create a transaction or an invoice, see below.
  • Permanent — authentication and parameter errors. Fix the request instead of repeating it.

Validation requests (/api/withdrawal/validation/…) and lookups do not create anything and can be repeated.

The Merchant API has no idempotency key. A request that creates a transaction or an invoice can time out or fail after the API has already processed it, and repeating it can create a second one. After a timeout or a 5xx error, check whether it was created before you repeat it:

  • For payouts, check the transaction history and the wallet balance. See Get transaction history. Every payout request that passes validation creates a new transaction, even if it repeats an earlier one.
  • For invoices, look up the order by your orderId. See Get payment order. If you pass sciName, Volet.com rejects a second invoice with the same orderId for that Hosted Checkout.

If it is still unclear whether a payout was created, contact support before you send it again.

  • Introduction — base URL, authentication, and request format
  • Statuses — transaction and payment statuses