Перейти к основному содержимому

Ошибки

Если запрос не выполнен, API возвращает HTTP-статус ошибки и структурированный ответ с одной или несколькими ошибками в data.errors.

Ответ с ошибкой​

{
"status": "error",
"data": {
"errors": [
{
"errorMessage": "resourceNotFound",
"errorType": "GENERAL",
"errorId": "3f69d9b6",
"errorDescription": "Resource not found",
"errorField": null,
"params": [],
"requestParams": {}
}
]
}
}
ПолеОписание
errorMessageМашиночитаемый код ошибки. Используйте его при обработке ошибок.
errorTypeКатегория ошибки: FIELD (недопустимо одно поле, см. errorField), FORM (запрос в целом) или GENERAL.
errorIdИдентификатор этой ошибки. Записывайте его в лог и указывайте в обращениях в поддержку.
errorDescriptionОписание для человека. Не используйте его в логике программы: текст может меняться.
errorFieldПоле запроса, к которому относится ошибка, если есть.
paramsДополнительные параметры ошибки, если есть.
requestParamsПараметры запроса, связанные с ошибкой, если есть.

Частые коды ошибок​

В списке — коды, которые обычно нужно обрабатывать в интеграции. Он неполный: метод может вернуть и другие коды. Неизвестный errorMessage обрабатывайте как общую ошибку и записывайте его errorId в лог.

errorMessageЧто означает
missingRequestParameterНе передан обязательный параметр.
methodArgumentTypeMismatchУ параметра неверный тип, например текст вместо числа.
httpMessageNotReadableТело запроса — невалидный JSON или не соответствует ожидаемой структуре.
unrecognizedFieldВ теле запроса есть поле, которое метод не принимает.
badParametersExceptionОдин или несколько параметров недопустимы.
badFormatAmountExceptionСумма в неверном формате.
notEnoughMoneyExceptionНа кошельке-источнике недостаточно средств.
limitPerTransactionExceptionСумма превышает лимит на одну транзакцию.
limitPerMonthExceptionТранзакция превышает месячный лимит.
walletDoesNotExistКошелька из запроса не существует.
walletCurrencyIncorrectExceptionВалюта кошелька не соответствует запросу.
recipientDoesNotExistExceptionАккаунта получателя не существует.
paymentMethodNotAvailableForMerchantApiПлатёжный метод недоступен для вашего API.
resourceNotFoundЭндпоинта не существует.
attemptsHaveEndedExceptionАккаунт исчерпал часовой лимит запросов. См. Ограничение числа запросов.
tryAgainAfterAWhileДанные временно заблокированы. Повторите запрос позже.
serviceTemporaryUnavailableСервис временно недоступен. Повторите запрос позже.
internalServerErrorНепредвиденная ошибка сервера.

HTTP-коды​

СтатусЗначение
400Запрос сформирован неверно, содержит недопустимые параметры или не может быть обработан. Также возвращается, если не найден заказ или другая сущность.
401Заголовки аутентификации отсутствуют или недействительны, либо аккаунт исчерпал часовой лимит запросов (attemptsHaveEndedException).
404Запрошенный эндпоинт не найден.
405Эндпоинт не поддерживает этот HTTP-метод (httpMethodNotAllowed).
409Данные временно заблокированы (tryAgainAfterAWhile).
415Content-Type запроса не поддерживается (unknownContentType).
500Непредвиденная ошибка сервера (internalServerError).
503Сервис временно недоступен (serviceTemporaryUnavailable).

Не определяйте код ошибки только по HTTP-статусу: один и тот же статус может приходить с разными значениями errorMessage.

Обработка ошибок​

  • Записывайте errorId в лог для каждой ошибки.
  • Смотрите errorField, чтобы найти поле, которое нужно исправить.
  • После 401 проверьте имя API, email аккаунта, токен и время сервера по UTC.
  • Если у API нет прав на операцию или вашему серверу не разрешено его вызывать, проверьте права API и его белый список IP в разделе платёжных инструментов.

Безопасные повторы​

Ошибки делятся на две группы:

  • Временные — 409 (tryAgainAfterAWhile), 503 (serviceTemporaryUnavailable) и тайм-ауты. Запросы на чтение и проверку повторяйте, увеличивая паузу между попытками. О запросах, которые создают транзакцию или инвойс, — ниже.
  • Постоянные — ошибки аутентификации и параметров. Исправьте запрос, а не повторяйте его.

Запросы на проверку (/api/withdrawal/validation/…) и поиск ничего не создают, и их можно повторять.

В Merchant API нет ключа идемпотентности. Запрос, который создаёт транзакцию или инвойс, может завершиться тайм-аутом или ошибкой уже после того, как API его обработал, и повтор создаст вторую транзакцию или второй инвойс. После тайм-аута или ошибки 5xx сначала проверьте, создано ли это, и только потом повторяйте запрос:

  • Для выплат проверьте историю транзакций и баланс кошелька. См. Получение истории транзакций. Каждый запрос на выплату, прошедший проверку, создаёт новую транзакцию, даже если повторяет предыдущий.
  • Для инвойсов найдите заказ по вашему orderId. См. Получение платёжного заказа. Если вы передаёте sciName, Volet.com отклоняет второй инвойс с тем же orderId для этого Hosted Checkout.

Если по-прежнему неясно, создана ли выплата, обратитесь в поддержку, прежде чем отправлять её снова.

  • Введение — базовый URL, аутентификация и формат запросов
  • Статусы — статусы транзакций и платежей