Ошибки
Структура ответа, перечень кодов ошибок и порядок реакции
Формат ответа
Все ответы API возвращаются с HTTP‑кодом 200 OK. Логический результат определяется полем status в теле ответа.
Значение status | Описание |
|---|---|
Success | операция выполнена успешно; data заполнено, codeError равно none |
Warning | бизнес‑ошибка; data пустое, причина указана в codeError и message |
AuthError | ошибка аутентификации |
AccessError | токен валиден, но действие не разрешено |
HTTP‑коды, отличные от 2xx, возникают только при внутренних сбоях платформы. В этом случае структура тела не гарантируется. Для подобных ответов применяется повторная отправка запроса.
Коды ошибок
codeError | Условие возникновения | Реакция мерчанта |
|---|---|---|
none | успешное выполнение | — |
internalError | внутренний сбой платформы | повторная отправка через интервал с экспоненциальной задержкой |
invalidRequestParameters | нарушение формата запроса, отсутствие обязательного поля, недопустимое значение enum | исправление запроса на стороне мерчанта; повтор без изменений недопустим |
duplicateIdentifier | повторное использование idTransactionMerchant в пределах мерчанта | получение существующей операции через GET /operation/operation/platform/{id} |
noSuitableTariffForRequest | метод или направление не разрешены тарифом мерчанта | обращение к менеджеру для расширения тарифа |
noPaymentDetailsAvailable | отсутствуют свободные реквизиты для указанного метода и банка | смена paymentMethod или повтор через интервал |
notEnoughMoneyOnBalance | для Pay Out — недостаточно средств с учётом комиссии | пополнение баланса или снижение суммы |
fraud | операция отклонена антифрод‑контролем | проверка корректности полей clientID, clientIP, clientDateCreated |
Порядок реакции
| Условие | Допустимость повтора |
|---|---|
HTTP 5xx, сетевой таймаут, разрыв соединения | да, с тем же idTransactionMerchant, с экспоненциальной задержкой |
Success | — |
Warning, codeError = duplicateIdentifier | нет; запрос состояния существующей операции |
Warning, codeError = internalError | да, с экспоненциальной задержкой |
Warning, codeError = invalidRequestParameters | нет; ошибка на стороне мерчанта |
Warning, codeError = fraud | нет |
Warning, прочие коды | нет; обработка в соответствии с таблицей выше |
AuthError, AccessError | нет |
Рекомендуемая стратегия экспоненциальной задержки: начальный интервал 1 секунда, удвоение, не более шести попыток. При превышении лимита формируется уведомление эксплуатации.
Идентификация запросов
Поле traceID обязательно к сохранению на стороне мерчанта для всех неуспешных ответов. Применяется при обращении в службу поддержки для корреляции записей в журналах платформы.
Финальный статус операции
Финальный статус failed не является кодом ошибки HTTP‑запроса. Создание операции, завершившейся отказом провайдера или антифрод‑контроля, возвращает успешный HTTP‑ответ со status: Success и идентификатором операции; финальный статус определяется отдельно через webhook или опрос состояния.