Ошибки HTTP-ответов

KVELL возвращает ошибки API в едином JSON-формате. Один HTTP-статус может соответствовать нескольким кодам, поэтому при обработке ответа учитывайте значение errors[].code.

Формат ответа

Пример ответа с ошибкой

{
  "errors": [
    {
      "code": 20098,
      "message": "amount: Field required"
    }
  ]
}

Параметры ответа

Параметр	Тип	Описание
errors	array	Список ошибок.
errors[].code	integer	Код ошибки.
errors[].message	string	Описание ошибки.

Список ошибок

Что входит в справочник

Ниже перечислены стандартные ошибки. Банковские причины отклонения транзакции передаются в поле error_code и описаны отдельно в разделе «Коды ошибок транзакции».

HTTP 400 — ошибка выполнения запроса

Код	Сообщение	Что означает и что делать
20001	Неверный api-key	Проверьте значение ключа и контур запроса.
20002	Неверная подпись	Подпишите точное тело отправляемого запроса и повторите запрос.
20003	Payment/Payout профиль не привязан к магазину	Обратитесь к менеджеру KVELL для настройки требуемого профиля.
20004	Сессия не найдена	Сессия отсутствует или истекла. Создайте новый сценарий операции.
20005	Ошибка от PSP сервиса	Платёжный сервис или банк вернул ошибку обработки после создания операции.
20007	Транзакция совершалась прежде	Операция с таким transaction уже существует. Запросите её статус, не создавайте дубликат.
20008	Не обработанный статус для проведения платежа	Получен статус, который нельзя обработать в текущем сценарии. Запросите актуальный статус операции.
20010	Неверный формат email	Исправьте email и повторите запрос.
20011	Неверная дата истечения срока счета	Исправьте дату истечения счёта и повторите запрос.
20012	Заказ не завершен	Дождитесь финального статуса заказа перед следующей операцией.
20013	Заказ не является платежом	Проверьте тип исходной операции.
20014	Ошибка при отправке email	Проверьте адрес получателя и повторите отправку позднее.
20015	Недостаточно средств	Операция с исходным transaction отменена. Пополните баланс и создайте новую попытку с новым transaction.
20016	Аккаунт не найден	Проверьте настройки аккаунта или обратитесь в поддержку.
20018	Необходимо выбрать один способ сохранения карты на стороне банка	Оставьте в запросе только один способ сохранения карты.
20019	Превышен лимит выплат по магазину	Уменьшите сумму или измените лимит, затем повторите запрос.
20022	Не удалось получить настройки терминала для проверки токена ТБанк	Проверьте настройки терминала или обратитесь в поддержку.
20023	Невозможно вернуть средства за незавершенную операцию	Дождитесь завершения исходной операции.
20024	Ошибка возврата средств	Проверьте статус исходной операции и возврата перед повтором.
20025	Сумма возврата превышает сумму заказа	Уменьшите сумму возврата.
20026	Невозможно сделать отмену в незавершенной операции	Дождитесь завершения исходной операции.
20027	Ошибка отмены предавторизации	Проверьте статус операции и обратитесь в поддержку при повторении ошибки.
20028	Невозможно сделать подтверждение незавершенной операции	Дождитесь статуса, допускающего подтверждение.
20029	Ошибка подтверждения предавторизации	Проверьте статус операции и обратитесь в поддержку при повторении ошибки.
20030	Сумма подтверждения превышает сумму заказа	Уменьшите сумму подтверждения.
20039	Sber профиль не привязан к магазину	Обратитесь к менеджеру KVELL для настройки Sber-профиля.

HTTP 401 — ошибка авторизации

Код	Сообщение	Что означает и что делать
20032	Неверный ключ	Проверьте ключ доступа и повторите запрос.

HTTP 403 — доступ запрещён

Код	Сообщение	Что означает и что делать
20037	Доступ запрещен	Убедитесь, что магазин активен и ему разрешён доступ к API.
20038	Некорректный номер черновика	У магазина нет доступа к указанному черновику выплаты.

HTTP 404 — данные не найдены

Код	Сообщение	Что означает и что делать
20006	Магазин не найден	Проверьте X-Api-Key и контур запроса.
20009	Заказ не найден	Проверьте transaction и магазин, от имени которого выполняется запрос.
20031	Данные по ключу не найдены в кэше	Данные отсутствуют или истекли. Повторите исходный сценарий их создания.
20033	Задача по получению справки не найдена	Проверьте идентификатор задачи.
20036	Договор не найден	Проверьте идентификатор договора.
20040	Черновик выплаты не найден	Проверьте идентификатор черновика и магазин.

HTTP 422 — ошибка валидации

Код	Сообщение	Что означает и что делать
20017	customer_key не задан	Передайте customer_key в сценарии, где он обязателен.
20020	Получатель не задан	Передайте данные получателя.
20021	Необходимо заполнить хотя бы одно поле	Передайте хотя бы одно изменяемое поле.
20041	Итоговое поле description превышает допустимую длину	Сократите description, сформируйте новую подпись и повторите запрос.
20042	Данные из выплаты и черновика выплаты не совпадают	Приведите данные запроса в соответствие с черновиком.
20098	Ошибка валидации поля	Исправьте поле, указанное в начале message, сформируйте новую подпись и повторите запрос.

HTTP 5XX — внутренняя ошибка

Код	Сообщение	Что означает и что делать
20000	Неизвестная ошибка	Результат операции неизвестен. Используйте алгоритм обработки технических ошибок ниже.

Технические ошибки и отсутствие ответа

Ответ 5xx, таймаут и разрыв соединения означают, что результат операции неизвестен: запрос мог быть обработан, даже если клиент не получил ответ.

1. Оставьте операцию в своей системе в состоянии «обрабатывается».
2. Запросите её статус по исходному transaction.
3. Не создавайте повторную операцию с новым transaction, пока результат исходной операции не установлен.
4. Если запросы статуса продолжают завершаться ошибкой, обратитесь в поддержку и передайте transaction.