Перейти к содержанию

Причины отказа

Причина отказа — сохранённая диагностическая запись с категорией type и необязательным описанием detail. Она может относиться к сессии целиком или к результату технологии. Наличие такой записи, отрицательный result, HTTP-ошибка запроса и окончательный статус сессии — разные признаки: проверяйте их совместно.

Эта страница описывает фактический контракт текущего backend. Сообщения, которые только возвращаются отдельным HTTP-запросом или записываются в технический журнал, не становятся автоматически failure_reason.

Где получить причины отказа

Полный и light-результаты Flow Session используют одинаковый формат ошибок:

  • POST /api/flows/sessions/result/ — полный результат;
  • POST /api/flows/sessions/result/light/ — light-результат;
  • <блок_технологии>.failure_reason — причина выбранного результата технологии;
  • flow_session_failure_reasons[] — причины самой сессии и выборка причин технологий. Это общий массив, а не только ошибки уровня сессии.

У сессии нет отдельного корневого failure_reason в этих ответах. В webhook место ошибки и правила включения полей зависят от события.

Структура и отсутствие значений

Поле Тип в JSON Условия
<блок>.failure_reason object Если у выбранной записи есть причина. Исключение — адрес, см. ниже.
failure_reason.type string, enum Обязательно внутри объекта, не null; точные значения — в таблице категорий.
failure_reason.detail string При наличии описания. Пустая строка допустима и сохраняется. Это диагностический текст, а не отдельный код ошибки.
flow_session_failure_reasons object[] В полном и light-ответе формируется массив, в том числе [].
flow_session_failure_reasons[].type string Обязательно, не null. Схема общего массива не ограничивает строку enum технологий: здесь встречается и EXPIRED.
flow_session_failure_reasons[].detail string При наличии описания.

Объект причины не содержит идентификатора, времени, кода технологии или номера попытки. В общем массиве нельзя надёжно восстановить источник ошибки только по позиции или тексту. Ограничение хранения detail — 512 символов; единого механизма безопасного усечения внешних сообщений код не задаёт.

Категории ошибок

Регистр значений значим. Название категории описывает способ классификации ошибки backend и само по себе не устанавливает виновника, возможность повторения или окончательность отказа.

type Значение Уровень и подтверждённое использование
EXPIRED Истёк срок действия сессии Сессия. Периодическая обработка просроченных незавершённых сессий.
OTHER Прочая причина Оба уровня. Ограничение по fingerprint, проверка хеша изображения, сообщения клиента.
CALC_RESULT Отрицательное решение или нарушение условия проверки Технологии. Оценки лица, правила документа, наличие записей в реестре, некоторые ошибки OTP. Может означать и отсутствие необходимых данных для расчёта.
SERVICE_ERROR Ошибка, отнесённая обработчиком к сервисной Технологии. Соединение, обработка, ответ поставщика. Иногда сюда попадают ошибки входных данных внешнего запроса.
REQUEST_ERROR Ошибка выполнения запроса Технологии. AML, MRZ и IP. Единого разграничения с SERVICE_ERROR для всех технологий нет.
CLIENT Ошибка, отнесённая обработчиком к клиентской Технологии. Отклонение доступа, входных данных, правил IP и анкеты.
TIMEOUT Превышение времени ожидания Технологии. В GBDFL и PPS — превышение времени опроса; также принимается от клиента. Не каждый тайм-аут имеет этот type.
NO_CAM Сообщение об отсутствии / недоступности камеры Объявлено для технологий и принимается входной схемой сообщения об ошибке.
DIFFERENT_FACES Несовпадение лиц между детекциями Liveness Технологии Liveness. Для самостоятельного Face2Face и NPCK несовпадение имеет CALC_RESULT.
VR_CAM Отрицательная проверка виртуальной камеры Технологии Liveness, сообщение VR Camera Attack.

Ошибки и итог проверки

  • result: false возможен без причины: начальное состояние некоторых реестров, найденное совпадение AML при включённом отказе по санкциям, отрицательный расчёт DR v1 без отдельной записи.
  • result: true возможен с причиной: подтверждённый пример — ГБД ЮЛ с allow_service_unavailable. Успешная запись значений в существующий результат также не означает универсальную очистку прежней ошибки.
  • result может ещё не иметь значения. API тогда исключает поле. У Liveness Core это возможно и при направлении на ручное рассмотрение.
  • У KZ Info и ЕРД поля result вообще нет: анализируйте статус получения данных и причину.

Статус сессии и flow_session_result

При штатном завершении наличие собственной причины сессии приводит к FAILED. Далее проверяются результаты активных технологий: неполное или отрицательное прохождение обычно даёт FAILED, успешное — FINISHED; для Liveness Core с неопределённым результатом предусмотрен IN_REVIEW. Полный перечень статусов — в обзоре результатов.

Публичный flow_session_result вычисляется отдельно:

  1. Пока статус не FINISHED и не APPROVED, возвращается false.
  2. Для выбранных результатов технологий наличие failure_reason или явного result: false даёт false.
  3. Отсутствие значения result само по себе не проверяется как false; отсутствие одиночной связи и пустая коллекция обрабатываются неодинаково.

В этом расчёте обходятся технологии Workflow без фильтра активности, кроме Person. Проверка статуса при завершении использует активные технологии и их результаты, а KZ Info/ЕРД считает завершёнными по статусам RECEIVED или FAILED. Поэтому возможны status: "FINISHED" и flow_session_result: false, в частности при сохранённой ошибке технологии. Ручное APPROVED также не отменяет проверки сохранённых ошибок в публичном агрегате. Собственные причины сессии напрямую в этом агрегате повторно не проверяются — они учитываются штатным завершением через статус.

Сохранение причины технологии обычно не меняет статус сессии немедленно. Исключения указаны ниже. Промежуточный отрицательный результат при PROGRESS не равен уже завершённой сессии FAILED.

Workflow

Причины уровня сессии находятся в flow_session_failure_reasons[].

type detail Когда возникает и последствия
EXPIRED Flow session was expired Периодическая задача находит expired_at в прошлом у сессии CREATED, PROGRESS или QR, добавляет причину и переводит сессию в FAILED.
OTHER Too many sessions by fingerprint При включённой проверке fingerprint число сессий данного Workflow с этим fingerprint за Fingerprint timeout (seconds) превышает Fingerprint timeout attempts, включая текущую запись. Сессия немедленно становится FAILED.
OTHER Динамический текст или без detail Клиентский метод записи ошибки сессии принимает описание. Само добавление причины не меняет статус; при последующем штатном завершении наличие записи приводит к FAILED.
EXPIRED Динамический текст или без detail Тот же входной метод допускает категорию EXPIRED; это не гарантирует, что сработала задача истечения срока.

Liveness

Публичный блок: liveness_result. Варианты Head Position, Short, Distance, Distance v2, Pro Max и Core используют общий блок. Его схема не возвращает статус обработки Liveness.

Расчёт живости

Ниже автоматические причины; они приводят к result: false и также устанавливают статус обработки FAILED.

type Точный detail Условие и смысл
CALC_RESULT Mask Attack При Enable mandatory mask attack check: Проверка масочной атаки отрицательна.
CALC_RESULT Closed eyes При Enable open eyes check: закрытые глаза у детекции
CALC_RESULT Low overall prediction Результат моделей не проходит threshold.
CALC_RESULT No face detected Не прошедшая модельная проверка при отсутствии результатов моделей, оценки и области лица у детекции.
CALC_RESULT No VR scoring data Включён VR cam scoring check, но запись необходимых данных VR-scoring отсутствует. Это отсутствие данных для проверки, а не доказанная виртуальная камера.
VR_CAM VR Camera Attack При VR cam scoring check отрицательный результат проверки на виртуальную камеру.
CALC_RESULT Several faces Включён Reject liveness when several faces are detected in the frame, в лучшей детекции известно число лиц и оно больше одного.
CALC_RESULT Age is too low Целая часть оценённого возраста ниже Age threshold, и условие перевода на ручное рассмотрение по Age manual threshold не выполнено. При отсутствии оценки возраста эта причина не создаётся.
CALC_RESULT Face comparison timeout При Enable face swap check during the process у неинициальной детекции нет результата сравнения к моменту итоговой проверки. Категория именно CALC_RESULT, не TIMEOUT.
CALC_RESULT Face comparison failed При той же настройке у неинициальной детекции отрицательный результат проверки.

Эти причины дают result: false и статус обработки FAILED. Liveness может выбрать IN_REVIEW без причины вместо отказа по пограничным оценкам живости или возраста; в публичном результате result тогда отсутствует. Состояние проверки оценивается после ожидания предусмотренных обработчиком фоновых расчётов, а не по одному промежуточному кадру.

Целостность изображения и ошибки клиента

type Точный detail Условие
OTHER Incorrect image hash В production проверка привязки изображения к сессии не прошла. Записывается причина и result: false; Liveness результат дополнительно получают FAILED.

Face2Face

Публичный блок: face2face_result. Статуса обработки в нём нет.

type Точный detail Условие и последствия
CALC_RESULT Different faces Сравнение отрицательно. При наличии конфигурации используется условие prediction >= threshold; при отсутствии — решение сервиса. result: false.
CALC_RESULT Several faces Fail if more than one face in frame включён и хотя бы на одном изображении больше одного лица. Имеет приоритет перед Different faces, принудительно ставит result: false, даже если сходство достаточно.
SERVICE_ERROR No face found Сервис сравнения сообщает, что лицо не найдено.
SERVICE_ERROR Can`t connect to face2face service Ошибка вызова сервиса сравнения.
OTHER Incorrect image hash Не прошла проверка хеша переданного изображения. Причина сохраняется до сравнения, result может отсутствовать.

Document Recognition

Публичный блок API и flow.end: document_recognition_v2_result. В отдельном technology.end DR2 обработчик использует имя data.document_recognition_result; не путайте его со структурой результата DR v1.

Ошибки получения результата:

type Точный detail Условие; result и статус
SERVICE_ERROR Document recognition service not available now Перехваченная ошибка API при запросе / обработке распознавания; false, FAILED.
CALC_RESULT Document not found Ответ распознавателя с success: false и error.message точно Document not found; false, NOT_FOUND.
SERVICE_ERROR Document recognition process was failed Другой обработанный ответ success: false; false, FAILED.

Ограничения Workflow после успешного распознавания проверяются последовательно. Первая сработавшая проверка создаёт причину и ставит result: false; статус распознавания остаётся SUCCESS. Это успешно распознанный, но отклонённый по правилам документ.

type Точный detail / шаблон Условие
CALC_RESULT Disallowed document country Непустой список разрешенных к проверке стран не пересекается со странами распознанных типов документа.
CALC_RESULT Disallowed document type Непустой список разрешенных к проверке типов документов не пересекается с распознанными типами документов.
CALC_RESULT Age is lower than minimal Задан Minimum holder age, optical_checks.text строго false, и выбранный возраст ниже минимума. Сначала берётся возраст визуальной зоны, а при его отсутствии — MRZ. Без условия text: false именно эта ветка не срабатывает.
CALC_RESULT Document is expired Включён Reject expired documents, optical_checks.expiry строго false.
CALC_RESULT MRZ is invalid. {missed_values} is missing. Включён Reject documents with invalid MRZ, имеется непустой MRZ JSON и отсутствуют требуемые значения. {missed_values} — строковое представление списка имён с одинарными кавычками, например ['date_of_birth']. Проверяются по порядку mrz_type, nationality_code, first_name, last_name, document_number, sex, age, date_of_birth; отсутствующим считается значение null или отсутствующий ключ.
CALC_RESULT Authenticity checks are not passed При Fail on authenticity check хотя бы одна из проверок подлинности страницы строго false: экран, чёрно-белая копия, графические шаблоны, штрихкод, сопоставление портретов, вклейка фото. Отсутствие данных не эквивалентно false.

E-Document

Публичные блоки: edocument_result и edocument_child_result. В сохраняющих ошибку ветках ниже устанавливаются result: false и status: "CANCELED". У сессии действует общий механизм завершения.

Доступ и соответствие документа

Блок / операция type Точный detail Условие
Обычный E-Document, проверка БМГ CLIENT Subject not found in MCDB Проверка Базы мобильных граждан не нашла пользователя. Дополнительно сохраняется is_subject_in_mcdb: false.
Обычный / детский, запрос доступа CLIENT Profile is not found Внешний ответ о ненайденном профиле, преобразованный в HTTP 404 обработчиком доступа.
Обычный, получение списка детей SERVICE_ERROR Profile is not found Та же ошибка профиля, но обработчик списка детей классифицирует все перехваченные API-ошибки как сервисные.
Обычный / детский, запрос доступа CLIENT Invalid IIN Внешний ответ о недопустимом ИИН преобразован в клиентскую ошибку.
Обычный, получение списка детей SERVICE_ERROR Invalid IIN Та же ошибка входных данных в обработчике списка детей.
Обычный / детский, запрос доступа CLIENT Document does not exist Поставщик сообщил об отсутствии документа. Для обычного удостоверения при Alternative VNZH (Residence Permit) check сначала возможен запрос ВНЖ; успешный запасной путь не создаёт эту причину.
Обычный / детский, подтверждение и получение CLIENT Document type is not the same as requested type Тип полученного документа не соответствует допустимому для запроса. Для обычного E-Document учитывается разрешённая замена удостоверения на ВНЖ.
Обычный E-Document CLIENT IIN from document does not match requested IIN Запрошенный и полученный ИИН известны и не совпадают при проверке ответа.
Детский E-Document, получение по коду CLIENT Document owner is not the same as requested owner Непустое запрошенное ФИО, собранное в верхнем регистре, не совпадает с ФИО владельца полученного документа.
Обычный / детский, подтверждение доступа CLIENT Access to document is not found or is not active Доступ не найден / неактивен.

Сервисные ошибки

Каждое сочетание ниже имеет type: "SERVICE_ERROR"; применяется к обычному или детскому блоку, если соответствующий вызов находится в сохраняющей ошибку операции.

Точный detail Условие
Can`t connect to E-Document service Ошибка соединения с сервисом.
Could not send request to E-Document service Ошибка отправки / ожидания запроса, преобразованная обработчиком в соответствующее исключение.
Government service error Не удалось разобрать ответ государственного сервиса как ожидаемый JSON; категория остаётся сервисной, в том числе для исключения с HTTP 424.
E-Document service is not available now Поставщик вернул ответ, отнесённый к недоступности, вместо обработанной ошибки профиля, документа или доступа.

Address

Публичный блок: address_result.

Ответ подтверждения доступа

type Точный detail Условие и последствия
CLIENT INVALID Отрицательный статус подтверждения доступа; сохраняется тот же статус технологии.
CLIENT TIMEOUT Статус тайм-аута подтверждения доступа; категория не TIMEOUT.
CLIENT NOT_FOUND КДП вернул статус отсутствия.
CLIENT FAILED КДП вернул FAILED.

Запрос токена и адреса

Операция type Точный detail Условие
Токен КДП SERVICE_ERROR Can`t connect to kdp service Ошибка соединения при запросе токена.
Токен КДП SERVICE_ERROR Invalid IIN КДП вернул ответ о невалидном ИИН.
Токен КДП SERVICE_ERROR Could not send request to address service Другой неуспешный HTTP-ответ от КДП
Получение адреса CLIENT Token Expired Срок токена уже прошёл.
Получение адреса SERVICE_ERROR Could not send request to address service Неуспешный запрос адреса, преобразованный в сервисное исключение.

GBDFL

Публичный блок: gbdfl_result. Начальная запись может иметь result: false без ошибки. Общие ошибки запроса токена совпадают с адресом:

Операция type Точный detail Условие
Токен SERVICE_ERROR Can`t connect to kdp service Ошибка соединения с КДП.
Токен SERVICE_ERROR Invalid IIN КДП вернул ответ о невалидном ИИН.
Токен SERVICE_ERROR Could not send request to address service Другой неуспешный HTTP-ответ КДП.
Данные SERVICE_ERROR Can`t connect to GBDFL service Ошибка соединения с сервисом ГБД ФЛ.
Данные SERVICE_ERROR A server error occurred. Неуспешный HTTP-ответ получения данных создаёт общее исключение; сохраняется его стандартное описание, а не тело ответа поставщика.
type Точный detail Условие и последствия
CLIENT INVALID Статус КДП INVALID, сохраняется причина и отрицательный результат.
CLIENT NOT_FOUND Статус КДП NOT_FOUND; причина не уточняет, что именно не найдено.
CLIENT FAILED Статус КДП FAILED.
CLIENT TIMEOUT Статус КДП TIMEOUT сразу сохраняется как причина.
SERVICE_ERROR GBDFL token request timed out multiple times Повторный TIMEOUT, пока сохранён маркер предыдущего тайм-аута (300 секунд); result: false, статус FAILED. Первый TIMEOUT позволяет повторный опрос и не создаёт эту причину.
TIMEOUT Session polling timeout exceeded Имеется запись результата и прошло больше 300 секунд от сохранённого начала опроса; result: false, статус FAILED.

Для отклонённых статусов сохраняется статус ответа КДП; сессия обычно завершается общим механизмом.

ГБД ЮЛ

Публичный блок: gbdul_result.

type Точный detail Условие и последствия
SERVICE_ERROR Cannot connect to GBDUL service Ошибка запроса или ответ поставщика, отнесённый к недоступности. Обычно result: false, FAILED. При Complete flow successfully on service error: true — result: true, ERROR_ACCEPTED, причина сохраняется.
SERVICE_ERROR Organization not found in GBDUL Обработанный ответ об отсутствии организации. result: false, FAILED; разрешение недоступности не принимает отсутствие организации. Категория именно сервисная, хотя исходное исключение имеет HTTP 404.

Возможность пройти технологию с ERROR_ACCEPTED не гарантирует положительный flow_session_result.

PPS

Публичный блок: pps_result.

Операция type Точный detail Условие и последствия
Опрос TIMEOUT Session polling timeout exceeded Есть результат и прошло больше 300 секунд от сохранённого начала опроса; false, FAILED.
Токен SERVICE_ERROR PPS token request timed out multiple times Повторный статус TIMEOUT в пределах срока маркера 300 секунд; false, FAILED. Первый такой ответ оставляет возможность опроса без новой причины.
Токен CLIENT INVALID Отрицательный статус КДП; result: false.
Токен CLIENT NOT_FOUND Статус КДП о ненайденных данных; result: false.
Токен CLIENT FAILED Статус КДП FAILED; result: false.
Токен SERVICE_ERROR Can`t connect to kdp service Ошибка соединения с КДП; false, FAILED.
Токен SERVICE_ERROR Invalid IIN КДП вернул ответ о невалидном ИИН; false, FAILED.
Данные CLIENT Can`t connect to PPS service Ошибка запроса или HTTP 5xx; false, FAILED.
Данные CLIENT PPS data is rejected Не доступно получение данных от потавщика; его тело не сохраняется в detail, используется стандартное сообщение; false, FAILED.
Данные CLIENT IIN data not found Субъект с данным ИИН не найден; false, FAILED.
Данные CLIENT PPS token request timed out Превышено время ожидания на получение токена; false, FAILED. Отличается и текстом, и категорией от повторного тайм-аута токена.
Данные SERVICE_ERROR A server error occurred. Прочий неуспешный HTTP-ответ; стандартное описание общего исключения вместо сформированного в сервисе текста PPS error: ...; false, FAILED.

При INVALID, NOT_FOUND, FAILED сохраняется соответствующий статус ответа КДП.

РПН

Публичный блок: rpn_result. Причины ниже дают result: false; ошибки вызовов — FAILED, отклонённый статус КДП сохраняется как статус технологии.

Операция type Точный detail Условие
Токен CLIENT INVALID КДП вернул INVALID.
Токен CLIENT TIMEOUT КДП вернул TIMEOUT.
Токен CLIENT NOT_FOUND КДП вернул NOT_FOUND.
Токен CLIENT FAILED КДП вернул FAILED.
Токен SERVICE_ERROR Can`t connect to kdp service Ошибка соединения с КДП.
Токен SERVICE_ERROR Invalid IIN КДП вернул ответ о невалидном ИИН
Данные SERVICE_ERROR Can`t connect to RPN service Ошибка запроса данных регистра.
Данные SERVICE_ERROR RPN service error Неуспешный HTTP-ответ или отсутствие необходимых данных в ответе регистра.

NPCK

Публичный блок: npck_result.

type Точный detail Условие
CALC_RESULT Different faces Полученное решение сравнения отрицательно; сохраняется и полученная оценка prediction.
CLIENT Invalid data passed Сервисом получены некорректные данные.
CLIENT Credentials not provided Ошибка учётных данных.
SERVICE_ERROR NPCK service unavailable Другая обработанная HTTP-ошибка.

Kz-Info

Публичный блок: kz_info_result, без булева result.

type Точный detail Условие и смысл
CALC_RESULT Existence in the debtor register Session failure on debtor presence включён и exec_proc_info непустой. Наличие исполнительных производств отклоняется правилами Workflow, хотя данные могли успешно прийти (RECEIVED).
SERVICE_ERROR Exec proc info request failed Session failure on debtor registry error включён и exec_proc_info_status: "FAILED".

ЕРД

Публичный блок: erd_result, без булева result.

type Точный detail Условие и смысл
CALC_RESULT Existence in the debtor register Session failure on debtor presence включён и result_json непустой. Найдены записи реестра, запрещённые настройкой Workflow.
SERVICE_ERROR Exec proc info request failed Session failure on debtor registry error включён и статус запроса FAILED. Несмотря на текст, причина относится к ЕРД.

AML

Публичный блок: aml_result, без отдельного статуса.

type Точный detail Условие и последствия
CLIENT personal_number and full_name not found Не удалось получить ни персональный номер, ни ФИО для запроса, и включён Fail on error; result: false.
REQUEST_ERROR AML request failed Перехваченная HTTP-ошибка AML-запроса при Fail on error; result: false.

При выключенном Fail on error эти обработанные ошибки дают result: true без новой причины. При найденном совпадении и Fail when found in sanctions lists сохраняется result: false без failure_reason. Если отказ по совпадениям выключен, результат может быть true при имеющихся совпадениях. Не все неожиданные исключения поставщика охвачены обработчиком: текст любого сбоя нельзя считать новой публичной причиной.

MRZ

Публичный блок: mrz_result.

type Точный detail / источник Условие и последствия
REQUEST_ERROR MRZ request failed В Flow перехвачена ошибка недоступности MRZ-сервиса: ошибка запроса, неожиданный HTTP-статус либо соответствующий вариант ответа. result: false, REQUEST_FAILED.
CLIENT Error while parsing MRZ или динамический текст Ошибка распознавания / проверки MRZ. result: false, PARSE_FAILED.

MxDocument

Публичный блок: mxdocument_result, без статуса обработки. Все перечисленные автоматические причины имеют SERVICE_ERROR и дают result: false.

Точный detail Условие
Cannot connect to MX-Document service Ошибка соединения.
Cannot decode MX-Document response Не удалось декодировать JSON ответа.
MX-Document extraction failed Ошибка получения данных от поставщика
MX-Document service not available Другой обработанный неуспешный HTTP-ответ.

Tunduk

Публичный блок: tunduk_result, без статуса обработки. Ошибка запроса паспорта сохраняет result: false.

type Точный detail / источник Условие
CLIENT Passport not found in Tunduk system Документ не найден в системе Tunduk
CLIENT Данные ответа поставщика Ошибки валидации входных данных
SERVICE_ERROR Can`t connect to Tunduk service Ошибка соединения.
SERVICE_ERROR Can`t connect to service via Timeout Тайм-аут запроса, преобразованный в HTTP 408; категория именно сервисная.
SERVICE_ERROR Tunduk service is not available now Другой неуспешный HTTP-ответ.

Проверка IP

Публичный массив: ip_check_results[]. Проверяются все переданные адреса; причины отдельного элемента не заменяют проверку остальных элементов. Булев result важнее попытки вывести итог из одного verdict.

Получение данных

type Точный detail Условие и последствия
REQUEST_ERROR No IP addresses were found Список IP пуст. Создаётся отрицательный результат с verdict: "suspicious" независимо от Fail on error.
SERVICE_ERROR No providers available Не создан ни один доступный поставщик. Отрицательные результаты для адресов, suspicious, независимо от Fail on error.
REQUEST_ERROR All provider requests failed Для всех либо отдельного IP нет разобранных данных и включён Fail on error. result: false, suspicious.

Проверка полученных признаков

Проверки выполняются в порядке таблицы; выбирается первая сработавшая. Причина даёт result: false, обычно verdict: "blocked" при наличии данных.

type Точный detail Условие
CLIENT VPN detected Reject VPN and proxy IP addresses и признак VPN.
CLIENT Proxy detected Reject VPN and proxy IP addresses и признак proxy, если не сработала проверка VPN.
CLIENT Datacenter detected Reject data center IP addresses и признак hosting.
CLIENT High risk score Целочисленный risk больше выставленного порога.
CLIENT Country mismatch: {country_code} Block on IP country mismatch, активна обычная технология E-Document, страна IP не KZ. При отсутствии кода в тексте может быть None. Это сравнение с ожидаемым KZ, а не с прочитанным гражданством документа.

Если эта функция будет вызвана, она изменит только ранее положительные IP-результаты: ставит false и причину, но не меняет verdict. Поэтому предусмотрена запись verdict: "ok" с ошибкой страны, но активный путь её формирования этой функцией не подтверждён.

Анкеты

Публичный массив: questionnaire_results[].

type Точный detail Условие и последствия
CLIENT Required questions were not answered При отправке анкеты отсутствуют сохранённые ответы на обязательные вопросы. result: false, статус обработки FAILED.

Одноразовый код (OTP)

Публичный массив: otp_results[].

type Точный detail / шаблон Условие и последствия
CALC_RESULT phone_number_missing Телефон не передан в запросе и не найден в metadata.otp.phone_number. Создаётся запись с пустой строкой телефона, result: false, status: "failed".
SERVICE_ERROR Telegram Gateway error: {error} При проверке кода шлюз вернул ok: false; {error} — значение error ответа либо запасное unknown error. result: false, failed.
CALC_RESULT expired При проверке провайдер сообщил об истечении срока; result: false, expired.
CALC_RESULT revoked Провайдер сообщил об отзыве; в локальном результате также result: false, expired, а не cancelled.
CALC_RESULT Динамический статус провайдера Проверка отрицательна, статус не expired/revoked, после увеличения числа попыток достигнут Maximum attempts. result: false, wrong_code; detail сохраняет статус источника.

DS Identifier / DS NPCK / DS Signer

Публичные блоки: ds_identifier_result и ds_signer_result. DSI и DSN используют общий блок идентификации. Статусы обработки ЭП этими блоками не возвращаются.

Идентификация DSI / DSN

В сохраняющих ветках result: false, статус обработки FAILED.

Вариант type Точный detail Условие
DSI CLIENT Digital Signature invalid input Сервис ЭП отклонил входные данные в операции, использующей такое преобразование ответа.
DSI / DSN CLIENT Digital Signature Organization does not exist Ответ сервиса об отсутствии организации при получении / создании клиента.
DSI / DSN CLIENT Digital Signature Client does not exist Ответ об отсутствии клиента при работе с клиентом организации.
DSI / DSN CLIENT Digital Signature Organization Client does not exist Ответ об отсутствии связи клиента с организацией.
DSI, загрузка документа CLIENT Digital Signature Identity card does not exist Отсутствие документа при загрузке данных в ЭП. При первоначальном получении документа эта ошибка перехватывается отдельно и запускает запрос доступа, без причины отказа.
DSI CLIENT Document type is not the same as requested type При подтверждении доступа получен документ, который не является удостоверением личности или ВНЖ.
DSI CLIENT IIN from document does not match requested IIN При подтверждении известные ИИН запроса и полученного документа различаются.
DSI / DSN SERVICE_ERROR Cannot connect to Digital Signature service Ошибка соединения в перехваченной операции сервиса ЭП.
DSI / DSN SERVICE_ERROR Digital Signature service is not available now Другой обработанный неуспешный ответ сервиса ЭП.
DSN, загрузка ГБД ФЛ SERVICE_ERROR Could not upload Gbdfl data Ошибка HTTP при загрузке данных ГБД ФЛ, преобразованная в это исключение.

Подписание DSS

Сохранённые ошибки инициализации сертификата, перевыпуска и подписания дают result: false, статус обработки FAILED.

Операция type Точный detail / источник Условие
Инициализация сертификата / подписание SERVICE_ERROR Can`t connect to Digital Signature Signer service Ошибка соединения с сервисом подписания.
Перевыпуск сертификата SERVICE_ERROR Cannot connect to Digital Signature service Ошибка соединения при перевыпуске; используется сообщение сервиса идентификации.
Сертификат / подписание SERVICE_ERROR Digital Signature Signer service is not available now Серверная ошибка поставщика.
Сертификат / подписание CLIENT Динамический message ответа; запасное Digital Signature Signer client organization not found HTTP 404 поставщика.
Сертификат / подписание CLIENT Динамический message ответа; запасное Digital Signature Signer MS Cloud service has troubles with handling this request Другой HTTP 4xx поставщика.
Загрузка документов SERVICE_ERROR Can`t connect to Digital Signature Signer service Ошибка соединения при загрузке.
Загрузка документов SERVICE_ERROR Digital Signature Signer service is not available now Серверная ошибка при загрузке.
Загрузка документов SERVICE_ERROR Динамический message ответа; те же запасные сообщения об организации / MS Cloud HTTP 4xx при загрузке.

При перевыпуске сертификата известные сообщения поставщика переводятся перед сохранением. Для ответов 4xx это CLIENT:

Точный публичный detail Условие: исходное сообщение поставщика
Password already set Пароль для пользователя уже установлен
Digital Signature invalid OTP code Неверный код подтверждения
Digital Signature too many invalid OTP codes Неверный код подтверждения. Количество попыток ввода кода подтверждения исчерпано.
Digital Signature OTP code not found Код подтверждения не найден - прошло много времени с момента отправки коды подтверждения. Либо количество попыток исчерпано

Этот словарь не гарантирует, что поставщик выдаёт каждое сообщение именно на перевыпуске. Он задаёт преобразование, если такое сообщение пришло в этой операции; остальные сообщения сохраняются как получены.

При принятии сертификата применяется тот же перевод, но новая причина отказа не сохраняется. При подписании сообщение, содержащее неверный пароль без учёта регистра, превращается в HTTP-ошибку Digital Signature incorrect certificate password без новой причины и без перевода записи в FAILED; это позволяет исправить пароль и повторить вызов при сохранении остальных условий. Invalid verification code из старой страницы не подтверждён как фиксированная причина текущего кода.

Причины, формируемые интерфейсом

Интерфейс проверки сам фиксирует часть причин отказа: когда пользователь не дал доступ к камере, закрыл окно, не уложился в отведённое время или произошёл сетевой сбой. Эти причины попадают в failure_reason наравне с причинами сервера, описанными выше. Раздел отвечает на два вопроса: почему интерфейс записал причину и что в этот момент увидел пользователь. Сами экраны описаны в разделе Что видит пользователь.

Категории

Интерфейс использует те же категории type, что и сервер:

type Когда интерфейс её выбирает
NO_CAM Камера недоступна, доступ не дан или устройство не найдено
TIMEOUT Истекло время шага (Liveness, сканирование документа)
CLIENT Действие пользователя (закрытие, отказ), исчерпанные попытки, ответ сервера с кодом 4xx, не пройденные локальные проверки
REQUEST_ERROR Ответ сервера с кодом 5xx или пустой ответ
OTHER Сетевой сбой без ответа, неклассифицированная ошибка

Поле detail содержит короткое пояснение. Для ошибок уровня сессии в detail записывается журнал последних сбоев запросов в формате JSON, обрезанный до 512 символов.

Различайте по detail, а не по type

Категория CLIENT объединяет и действия пользователя (закрыл окно, отказался от согласия), и исчерпанные попытки, и ответы сервера с кодом 4xx. Чтобы отличить отказ пользователя от ошибки сервиса, читайте detail: Operation aborted by user, Consent declined by user и другие значения из таблиц ниже.

Уровень сессии

type detail Условие Что видит пользователь
CLIENT Снимок ответа сервера Не удалось получить настройки или подтвердить сессию Экран загрузки с текстом «Сессия не активна»
CLIENT Too many sessions by fingerprint Сервер отклонил сессию по ограничению на устройство «Слишком много попыток, пожалуйста, попробуйте снова позже»
NO_CAM — Доступ к камере запрещён политикой браузера или устройства, либо на телефоне нет камеры Финальный экран «Вы не дали доступ к камере!» с кнопкой «перезагрузить»
CLIENT Consent declined by user Нажата «Отказаться и выйти» на странице согласия Финальный экран
CLIENT Operation aborted by user Пользователь закрыл интерфейс и подтвердил закрытие Финальный экран
REQUEST_ERROR Ответ сервера Ошибка 4xx при ожидании завершения проверки на телефоне (QR) Финальный экран
REQUEST_ERROR IP check failed Сбой сервера при проверке IP Финальный экран

На десктопе без камеры причина не записывается: пользователь получает QR-код и продолжает на телефоне.

Если согласие не удалось зарегистрировать, под кнопкой появляется «Не удалось зарегистрировать согласие. Попробуйте ещё раз». Пользователь может повторить запрос; само сообщение не завершает сессию отказом.

Liveness

Запись Условие Что видит пользователь
NO_CAM, detail = имя и текст ошибки браузера Камера не запустилась: нет доступа, занята другим приложением, не найдена Экран повтора: «…так как не предоставили доступ к камере»
TIMEOUT Истекло время задания без явной причины Экран повтора: «Вы не прошли предыдущую проверку, попробуйте снова»
CLIENT Illumination check failed Не пройдена проверка освещения «Не хватило освещения. Найдите место, где свет падает на лицо»
CLIENT Medical mask check failed Обнаружена маска «Лицо было частично закрыто. Снимите маску…»
CLIENT Glasses check failed Обнаружены очки «Очки помешали проверке. Снимите их перед новой попыткой»
CLIENT Face was not detected in most frames Лицо отсутствовало не менее чем в 40 % кадров «Лицо не попадало в кадр. Держите телефон прямо перед собой»
CLIENT, несколько лиц Несколько лиц не менее чем в 40 % кадров «В кадре было несколько человек. Проходите проверку в одиночку»
CLIENT, расстояние Слишком далеко или близко не менее чем в 40 % кадров «Слишком далеко» / «Слишком близко»
CLIENT Virtual camera detected Название камеры совпало со списком виртуальных камер Экран повтора без объяснения причины
CLIENT Eyes were closed for more than 30 seconds Глаза закрыты дольше 30 секунд Отказ без экрана повтора
REQUEST_ERROR Пустой ответ сервера или ошибка 5xx «Ошибка соединения. Проверьте интернет и попробуйте снова»
Отказ сервера Сервер вернул отрицательный результат живости «Проверка не подтверждена. Убедитесь, что лицо хорошо видно»

Решение сервера (маска, возраст, несколько лиц, VR-камера по данным телеметрии) записывается сервером, см. Liveness.

Документы

Запись Условие Что видит пользователь
TIMEOUT Истекло время сканирования (MRZ, MX-Document) Отказ
CLIENT Operation aborted by user Закрыт экран камеры или загрузки Финальный экран
NO_CAM / OTHER Ошибка запуска камеры Экран повтора с текстом про камеру
CLIENT Too many tries + <причина> Исчерпаны попытки Document Recognition v2 Отказ

Сообщения на экране повтора Document Recognition v2:

Сообщение Условие
«Документ не обнаружен. Попробуйте снова с лучшим расположением и освещением» В кадре не найден документ
«Отсканирована одна и та же сторона документа. Переверните документ и отсканируйте другую сторону» Дважды показана одна сторона
«Операция была прервана пользователем» Пользователь закрыл сканер
«При обработке документа произошла ошибка сервера. Попробуйте снова» Сбой обработки
«Время ожидания истекло» Истекло время распознавания
«Камера недоступна» / «Камера не найдена» / «Доступ к камере запрещён» Проблемы с камерой
«Версия вашего браузера не поддерживается» Устаревший браузер
«Web-компонент не работает по протоколу HTTP» / сообщение о небезопасном контексте Страница открыта не по HTTPS

Эти причины (NO_DOCUMENT_FOUND, SAME_SIDE_TWICE, OPERATION_ABORTED, BACKEND_ERROR, ошибки камеры и браузера) записываются в detail последней попытки. Ошибки распознавания самого документа (несоответствие типа, страны, стороны, нечитаемый файл) отображаются на экране и на сервер как отдельная причина не уходят: сервер записывает собственную причину по результату распознавания.

Для MX-Document интерфейс также показывает следующие сообщения:

Сообщение Условие
«QR-код не обнаружен. Пожалуйста, убедитесь, что QR-код хорошо виден в рамке» На документе не читается QR-код
«Не удалось распознать MX документ» Документ не распознан
«Недопустимое расширение файла» Формат файла не поддерживается
«Максимальный размер файла — 24 МБ» Превышен допустимый размер файла
«Неверная страна документа» Загружен документ другой страны

E-Document и электронная подпись

Запись Условие Что видит пользователь
CLIENT Исчерпаны попытки ввода данных или кода Сообщение о лимите, затем отказ
OTHER The user has no registered minor children in Egov В E-Document Child у родителя нет детей в eGov «Несовершеннолетние не найдены»
CLIENT 5 неверных СМС-кодов в DS Identifier «Вы превысили максимальное кол-во ввода SMS-кода»
CLIENT 5 неверных паролей в DS Signer Отказ, финальный экран подписания
CLIENT Operation aborted by user Закрытие любого экрана Финальный экран подписания

Ошибки самих сервисов eGov и подписи (ИИН не найден, нет доступа, сервис недоступен) показываются пользователю текстом и записываются сервером.

Сообщения E-Document:

Сообщение Условие
«Недействительный ИИН» ИИН не прошёл проверку
«Телефон или ИИН не найдены в базе данных eGov» Номер не привязан к ИИН в eGov
«Не удалось установить соединение с сервисом e-document» Сервис eGov недоступен
«Полученный СМС-код введен неверно» / «Неверный OTP-код» Ошибка ввода кода
«Исчерпаны попытки ввода смс-кода» Исчерпаны попытки ввода
«Вы превысили максимальное кол-во ввода SMS-кода» Исчерпан лимит на стороне eGov
«Профиль не найден» и пояснение У пользователя нет профиля в eGov или БМГ
Прочие сообщения сервиса Документ не найден, нет доступа, выполнен повторный запрос или подписка не активна

Для E-Document Child отсутствие детей сопровождается сообщением «Несовершеннолетние не найдены» и завершает проверку отказом.

Сообщения электронной подписи:

  • DS Identifier: «Неверный формат ИИН», «Отсутствует файл», «Ошибка при загрузки файла», «Данные введены не корректно». Ошибки сервиса сообщают об отсутствии доступа или связи с сервисом, существующей или не найденной сессии, не найденной организации или клиенте, несовпадении ИИН или типа документа. При неизвестной ошибке показывается «Сервис Цифровой Подписи в данный момент недоступен».
  • DS NPCK: «Неверный OTP-код», «Не удалось отправить SMS клиенту», «Вы превысили максимальное кол-во попыток ввода кода», «Сервис Цифровой Подписи в данный момент недоступен». Сообщение также повторяется на финальном экране подписания.
  • DS Signer: при создании пароля — «PIN должен содержать 4 цифры» и «Пароли не совпадают»; при перевыпуске сертификата — «Код должен содержать 6 цифр». Ошибки сервиса сообщают о неверном пароле, непринятом сертификате, незагруженных документах, слишком большом числе неверных кодов, уже установленном пароле или непройденном Face2Face. При неизвестной ошибке показывается «Сервис Цифровой Подписи в данный момент недоступен».

OTP и анкета

Запись Условие Что видит пользователь
REQUEST_ERROR Failed to retrieve questionnaire Не удалось загрузить анкету Отказ без сообщения
REQUEST_ERROR Не удалось отправить ответы анкеты Отказ без сообщения
Статус failed или cancelled от сервера OTP отклонён сервером Отказ без сообщения
CLIENT Operation aborted by user Закрытие экрана Финальный экран

Сообщения OTP:

Сообщение Условие
«Не удалось отправить код. Попробуйте ещё раз» Сбой отправки
«Этот номер телефона недоступен. Проверьте номер и попробуйте снова» Провайдер отклонил номер
«Неверный код подтверждения» Ошибка ввода
«Срок действия кода истёк» Код устарел; новый отправляется автоматически
«Исчерпаны попытки отправки кода» Исчерпан лимит отправок

В анкете ошибки полей показываются на месте: «Это поле обязательно для заполнения», «Доступ к камере запрещён», «Ничего не найдено». Если анкету не удалось загрузить или отправить, проверка завершается отказом без отдельного сообщения на экране.

Реестры и фоновые проверки

Для GBDFL, PPS, Address, GBDUL, AML, IP Check, РПН и KZ Info интерфейс не показывает пользователю текст ошибки: при сбое проверка завершается отказом.

Запись Условие
OTHER ERR_NETWORK Нет ответа от сервера (сетевой сбой)
REQUEST_ERROR Ответ 5xx после исчерпания повторов
CLIENT Ответ 4xx, повтор не выполняется
CLIENT Исчерпаны попытки ввода в Tunduk

В формах реестров показываются «Неверный формат ИИН» и «Неверный формат БИН». Если Tunduk не находит данные, пользователь видит «Данные не найдены. Проверьте правильность заполненных данных».

Правила повторов для опросных технологий (GBDFL, PPS, Address):

  • статус «ожидание» от сервера опрашивается каждые 15 секунд без ограничения по числу итераций;
  • сетевой сбой и ответы 5xx повторяются до 4 раз подряд с паузой 15 секунд, затем отказ;
  • ответ 4xx завершает проверку сразу.

Ошибки форм

Сообщения под полями не прерывают проверку и не записываются как причина отказа: «Поле обязательное для заполнения», «Неверный формат ИИН», «Неверный формат БИН», «Неверный PIN-код», «Пожалуйста, заполните все поля», «Разрешите доступ к камере, чтобы продолжить».