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": {}
}
]
}
}
| Field | Description |
|---|---|
errorMessage | Machine-readable error code. Use it in your error handling. |
errorType | Error category: FIELD (one field is invalid, see errorField), FORM (the request as a whole), or GENERAL. |
errorId | Identifier of this error. Log it and include it in requests to support. |
errorDescription | Human-readable description. Do not use it in program logic: the text may change. |
errorField | The request field related to the error, if any. |
params | Additional parameters of the error, if any. |
requestParams | Request 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.
errorMessage | What it means |
|---|---|
missingRequestParameter | A required parameter is missing. |
methodArgumentTypeMismatch | A parameter has the wrong type, for example text instead of a number. |
httpMessageNotReadable | The request body is not valid JSON or does not match the expected structure. |
unrecognizedField | The request body contains a field the method does not accept. |
badParametersException | One or more parameters are invalid. |
badFormatAmountException | The amount has an invalid format. |
notEnoughMoneyException | The source wallet does not have enough funds. |
limitPerTransactionException | The amount exceeds the limit for one transaction. |
limitPerMonthException | The transaction exceeds the monthly limit. |
walletDoesNotExist | The wallet in the request does not exist. |
walletCurrencyIncorrectException | The wallet currency does not match the request. |
recipientDoesNotExistException | The recipient account does not exist. |
paymentMethodNotAvailableForMerchantApi | The payment method is not available for your API. |
resourceNotFound | The endpoint does not exist. |
attemptsHaveEndedException | The account has used up its hourly request limit. See Request limits. |
tryAgainAfterAWhile | The data is temporarily locked. Retry later. |
serviceTemporaryUnavailable | A service is temporarily unavailable. Retry later. |
internalServerError | Unexpected server error. |
HTTP status codes
| Status | Meaning |
|---|---|
400 | The request is malformed, contains invalid parameters, or cannot be processed. Also returned when an order or other entity is not found. |
401 | Authentication headers are missing or invalid, or the account has used up its hourly request limit (attemptsHaveEndedException). |
404 | The requested endpoint was not found. |
405 | The endpoint does not support this HTTP method (httpMethodNotAllowed). |
409 | The data is temporarily locked (tryAgainAfterAWhile). |
415 | The Content-Type of the request is not supported (unknownContentType). |
500 | Unexpected server error (internalServerError). |
503 | A 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
errorIdfor every error. - Check
errorFieldto 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 passsciName, Volet.com rejects a second invoice with the sameorderIdfor that Hosted Checkout.
If it is still unclear whether a payout was created, contact support before you send it again.
Related
- Introduction — base URL, authentication, and request format
- Statuses — transaction and payment statuses