Коды ошибок

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

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

{
  "statusCode": 403,
  "message": "NO_REQUISITE_FOUND_FOR_THIS_AMOUNT",
  "error": "Forbidden"
}

Если запрос не прошёл проверку схемы, message будет массивом — по строке на каждое нарушенное правило:

{
  "statusCode": 400,
  "message": [
    "amount must not be less than 1",
    "requisite should not be empty"
  ],
  "error": "Bad Request"
}

Авторизация и доступ

Код	HTTP	Что произошло и что делать
`INVALID_API_KEY`	401	Заголовок `X-Secure-Key` отсутствует или ключ не найден. Проверьте ключ в кабинете и убедитесь, что не используется ключ другого контура
`INVALID_TOKEN`	401	Передан токен сессии вместо API-ключа либо токен просрочен. Для серверных интеграций используйте `X-Secure-Key`
`IP_NOT_IN_WHITELIST`	403	Ключ верный, но адрес запроса не в списке разрешённых. Согласуйте адрес с менеджером — см. IP Whitelist
`CANT_CREATE_TRADE_MERCHANT_DISABLED`	403	Создание сделок для кабинета выключено. Обратитесь к менеджеру

Ошибки этой группы не устраняются повтором запроса.

Параметры запроса

Код	HTTP	Что произошло
`INVALID_PARAMS`	400	Передана недопустимая комбинация полей
`MISSED_PARAMS`	400	Не хватает обязательного параметра
`BANK_REQUIRED`	400	Для выбранного метода банк обязателен
`SPECIFY_REQUISITES_OR_SBP_NUMBER`	400	В `requisite` не передан ни номер карты, ни номер СБП
`MIN_FIAT_AMOUNT_SHOULD_BE_MORE_THAN_<n>`	403	Сумма меньше минимальной. Минимум подставляется в конец кода числом
`QR_DAILY_LIMIT_USER_ID_REQUIRED`	400	Для метода с суточным лимитом нужен `payerInfo.userId`

Создание сделки

Код	HTTP	Что произошло и что делать
`NO_REQUISITE_FOUND_FOR_THIS_AMOUNT`	403	Нет свободного реквизита под эту сумму и условия. Повторите позже или ослабьте условия — например, не указывайте `bank`
`ORDER_WITH_SPECIFIED_MERCHANT_TRANSACTION_ID_ALREADY_EXISTS`	403	`merchantTransactionId` уже использован. Сделка уже создана — запросите её вместо повторного создания
`INSUFFICIENT_FUNDS`	403	На балансе недостаточно средств для выплаты. Пополните баланс
`RATE_NOT_SET_CONTACT_SUPPORT`	403	Для валюты не задан курс. Обратитесь к менеджеру
`INTEREST_RATE_NOT_FOUND_FOR_METHOD_OR_CURRENCY`	403	Для пары метод + валюта нет ставки. Обратитесь к менеджеру
`CURRENCY_UNAVAILABLE_CONTACT_SUPPORT`	403	Валюта недоступна для кабинета. Обратитесь к менеджеру
`COUNTERAGENT_BLACKLISTED`	403	Контрагент в чёрном списке, реквизит выдан не будет
`MATCHING_METHOD_NOT_ALLOWED`	400	Метод не поддерживается в matching-сценарии — см. Matching

Отключённые методы

Все коды этой группы возвращаются с HTTP 403 и означают одно: метод не включён для вашего кабинета. Включение согласуется с менеджером.

Код	Метод
`CARD_METHOD_DISABLED_PLEASE_CONTACT_SUPPORT`	Перевод по карте
`SBP_METHOD_DISABLED_PLEASE_CONTACT_SUPPORT`	СБП
`ACCOUNT_METHOD_DISABLED_PLEASE_CONTACT_SUPPORT`	Перевод на счёт
`QR_METHOD_DISABLED_PLEASE_CONTACT_SUPPORT`	QR
`CROSS_BORDER_CARD_METHOD_DISABLED_PLEASE_CONTACT_SUPPORT`	Трансграничный перевод по карте
`CROSS_BORDER_SBP_METHOD_DISABLED_PLEASE_CONTACT_SUPPORT`	Трансграничный СБП

Операции с существующей сделкой

Код	HTTP	Что произошло
`TRADE_NOT_FOUND`	400 / 403 / 404	Сделка не найдена, принадлежит другому кабинету либо её статус не допускает эту операцию
`TRADE_NOT_FOUND_FOR_UPDATE`	400 / 403	Сделка найдена, но её текущий статус не позволяет изменение
`TRADE_ALREADY_PROCESSING`	403	Сделка уже обрабатывается, параллельное изменение отклонено
`TRADE_TIMEOUT_DECLINED`	400	Продление таймера отклонено — оно одноразовое

Споры и файлы

Код	HTTP	Что произошло
`MERCHANT_DISPUTE_CREATE_WINDOW_EXPIRED`	400	Прошло больше 14 дней с создания сделки
`MERCHANT_MAX_APPEALS_PER_TRADE_REACHED`	400	Исчерпан лимит споров по этой сделке
`FILE_MAX_5_MB`	400	Файл больше 5 МБ
`MIME_TYPE_NOT_SUPPORTED`	400	Формат файла не поддерживается

Быстрые откупы

Код	HTTP	Что произошло
`INVALID_PARAMS`	400	В теле есть `amount`, `isMatching`, `matchingTransactionId` либо валюта не `RUB`
`FAILED_TO_GENERATE_QR_NSPK`	403	Не удалось получить данные QR
`QR_USER_DAILY_TRADE_LIMIT_REACHED`	403	Клиент исчерпал суточный лимит операций по QR
`QR_DAILY_LIMIT_UNAVAILABLE`	503	Проверка суточного лимита временно недоступна

Ошибки на нашей стороне

Код	HTTP	Что делать
`INTERNAL_SERVER_ERROR`	403 / 500	Повторить с задержкой. Если ошибка устойчива — обратиться в поддержку, указав `merchantTransactionId`
`QR_DAILY_LIMIT_UNAVAILABLE`	503	Повторить позже: сделка не создана

Как обрабатывать ошибки

Повторять можно INTERNAL_SERVER_ERROR, QR_DAILY_LIMIT_UNAVAILABLE, сетевые тайм-ауты и NO_REQUISITE_FOUND_FOR_THIS_AMOUNT — с задержкой и ограниченным числом попыток.

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

Повторять опасно запросы на создание сделки, если ответ не получен из-за тайм-аута. Сделка могла быть создана. Порядок действий в этом случае — в разделе Надёжность интеграции.