Коды ошибок
Коды ошибок
На странице собраны коды ошибок для сценариев аутентификации, биометрии, Identity API и операций с организациями.
1. HTTP-статусы ответа для ошибок
Используемые HTTP-статусы ответа для ошибок:
400
Некорректный запрос.
401
Авторизация не пройдена.
403
Клиент не имеет необходимых разрешений для ресурса.
404
Запрошенный ресурс не найден.
405
Метод не поддерживается.
406
Сервер не может выдать ответ в запрошенном формате.
429
Превышен лимит запросов.
500
Внутренняя ошибка сервера.
Ошибки пользовательских шагов (liveness, OTP, ЭЦП, согласие) передаются через redirect-механизм OAuth2 Authorization Code Flow. Пользователь перенаправляется на redirectUri с кодом ошибки в query-параметре по шаблону:
[redirectUri]?errorCode=[error code]&state=[state]
Эти ошибки не возвращаются напрямую в теле ответа, поэтому их следует обрабатывать на стороне фронтенда при получении управления обратно на redirectUri.
2. Аутентификация и биометрия
В этом разделе собраны ошибки для POST /v1/auth/generate-user-url, redirect-сценариев, POST /oauth2/token и получения отчёта по сессии.
2.1. Получение URL-адреса для перенаправления пользователя
На этапе получения URL-адреса для перенаправления пользователя (вызов метода POST /v1/auth/generate-user-url) используются следующие коды ошибок.
HTTP 400
FIELD_MISSING
Отсутствует обязательный параметр.
Проверьте спецификацию метода и убедитесь, что все обязательные поля переданы в теле запроса.
FIELD_INVALID
Указано некорректное значение параметра.
Проверьте формат и допустимые значения параметров согласно спецификации метода.
IIN_BLOCKED
Пользователь исчерпал 4 попытки прохождения liveness-проверки в пределах одной сессии.
Подождите 15 минут (по умолчанию), затем повторите попытку.
IIN_NOT_FOUND
ИИН не найден в государственной базе ГБДФЛ.
Проверьте корректность ИИН: он должен состоять из 12 цифр и соответствовать реально зарегистрированному физическому лицу.
PHONE_BELONGS_TO_ANOTHER_IIN_IN_BMG
Номер телефона принадлежит другому ИИН в базе ЦОИД и в Базе мобильных граждан (БМГ). Возможные причины: номер ранее был зарегистрирован на другого человека; данные в БМГ ещё не обновлены; ошибка при вводе ИИН или номера телефона.
Проверьте правильность ИИН и номера телефона. Убедитесь, что номер оформлен на клиента. Если данные верны, но ошибка сохраняется, клиенту следует обратиться к оператору связи для актуализации данных в БМГ.
NO_ACTIVE_CONTRACT
Отсутствует активный договор с организацией.
Обратитесь к менеджеру платформы для заключения или активации договора на использование сервиса.
GBDFL_PERSON_UNDER_18_YEARS
Пользователь младше 18 лет.
Используйте сервис только для совершеннолетних пользователей. Реализуйте проверку возраста на стороне вашего приложения до запуска сценария.
INVALID_SCOPES
Некорректное значение scopes или нет прав на использование указанной области доступа. esign и organization_esign нельзя использовать одновременно.
Проверьте список scopes и разрешённые значения для вашего client_id. При необходимости расширить права — обратитесь к администратору платформы.
INVALID_REDIRECT_URI
redirectUri не совпадает с URI, зарегистрированным при регистрации приложения.
Передавайте URI строго в том виде, в котором он зарегистрирован на платформе, включая протокол, путь и параметры. При необходимости изменить URI обратитесь к администратору.
REQUIRED_PHONE
В запросе не передан параметр phone, обязательный при использовании scopes esign, organization_esign или otp. Номер телефона необходим для отправки одноразового кода подтверждения.
Передайте поле phone в теле запроса в международном формате.
PROVIDER_UNAVAILABLE
Внешний провайдер временно недоступен.
Повторите запрос через несколько секунд. Рекомендуется реализовать автоматический retry с нарастающей задержкой (exponential backoff).
PROVIDER_API_UNAVAILABLE
API провайдера вернуло ошибку (5xx или таймаут).
Повторите запрос через несколько секунд. При повторяющихся ошибках обратитесь в поддержку, передав requestId из ответа.
EMPLOYEE_IS_NOT_ALLOWED_TO_SIGN
Сотрудник не является руководителем и не входит в активную матрицу полномочий (актуально для scope organization_esign).
Проверьте, настроена ли матрица полномочий для данного сотрудника в личном кабинете организации.
ESIGN_BLOCKED
Использование облачной ЭЦП недоступно.
Проверьте статус облачной ЭЦП пользователя. Для разблокировки необходимо обратиться в НУЦ РК.
ESIGN_UNSIGNED_DOCUMENT
Документ не подписан.
Убедитесь, что процедура подписания документа завершена пользователем до отправки запроса на получение результата.
GBDFL_PERSON_INVALID_STATUS
Недопустимый статус пользователя в ГБДФЛ. Возможные значения: Capable — дееспособен; Imprisoned — осуждён; Missing — пропавший без вести.
Продолжение сценария невозможно. Пользователю следует обратиться в ЦОН или соответствующие государственные органы для уточнения своего статуса.
DOCUMENT_NOT_FOUND_IN_TEST_DB
Не найдены данные документа в тестовой базе данных. Используется только на тестовом окружении.
Убедитесь, что тестовый ИИН добавлен в тестовую базу. Уточните набор доступных тестовых данных у менеджера платформы.
HTTP 500
NO_ACTIVE_CONTRACT_WITH_VENDOR
Для организации не определён вендор, используемый для биометрической верификации.
Обратитесь к менеджеру платформы для настройки контракта с вендором биометрии.
GOV_SERVICE_UNAVAILABLE
Недоступны государственные базы данных (ГБДФЛ, ГБДЮЛ, КДП).
Повторите запрос позже. Если ошибка сохраняется более 10–15 минут, обратитесь в поддержку с requestId.
DOCUMENT_NOT_FOUND
Не найдены данные документа, удостоверяющего личность, в государственных базах данных. Возможные причины: клиент не является резидентом РК; отсутствие данных в государственных системах.
Пользователю следует обратиться в ЦОН для актуализации данных документа в государственных базах.
INTERNAL_ERROR
Внутренняя ошибка сервера.
Повторите запрос. При повторяющихся ошибках обратитесь в поддержку, передав requestId из ответа.
2.2. Подтверждение ИИН
На этапе подтверждения пользователем своего ИИН используются следующие redirect-ошибки.
auth_iin_step_cancelled
Пользователь нажал «Отменить» на этапе подтверждения ИИН.
Отобразите пользователю сообщение о прерванной операции и предложите начать авторизацию заново.
unauthorized
Некорректный URL для перенаправления или время действия ссылки истекло.
Сформируйте новую ссылку через POST /v1/auth/generate-user-url и убедитесь, что пользователь использует её в течение срока действия.
server_error
Внутренняя ошибка сервера.
Отобразите пользователю сообщение о временной ошибке и предложите повторить попытку позже.
network_connectivity_error
Сетевая ошибка во время сценария.
Проверьте стабильность соединения. Отобразите пользователю сообщение об ошибке сети и предложите повторить попытку.
2.3. Liveness-проверка и сопоставление фотоизображения
На этапе проведения liveness-проверки лица и процедуры сопоставления фотоизображения используются следующие redirect-ошибки.
gbdfl_photo_not_found
В государственной базе не найдено фото для сверки.
Продолжение сценария невозможно. Пользователю необходимо обратиться в ЦОН для актуализации биометрических данных.
gbdfl_face_not_matched
Не пройдена процедура сопоставления фото с государственной базой. Возможные причины: документ получен 10 и более лет назад — за это время внешность клиента могла измениться; неправильное освещение или ракурс при съёмке.
Предложите пользователю повторить попытку при хорошем освещении и без посторонних предметов перед лицом. Если ошибка повторяется — рекомендуйте обновить удостоверение личности в ЦОН.
gov_service_unavailable
Государственные базы данных временно недоступны.
Отобразите пользователю сообщение о временной недоступности сервиса и предложите повторить попытку позже.
gbdfl_person_under_18_years
Пользователь младше 18 лет.
Продолжение сценария невозможно. Реализуйте проверку возраста на стороне вашего приложения до запуска сценария.
liveness_attempts_exceeded
Исчерпано количество попыток прохождения liveness-проверки. Возможные причины: неправильное освещение или ракурс; технические сбои на стороне устройства; использование фото или видео вместо живого лица.
Отобразите пользователю сообщение об исчерпании попыток. Предложите начать сценарий заново, предварительно проверив условия съёмки: достаточное освещение, поддерживаемый браузер, живое лицо перед камерой.
invalid_liveness_session
Liveness-сессия повреждена, имеет неверный формат или принадлежит другому пользователю.
Не переиспользуйте данные liveness-сессий между пользователями. Начните новую сессию и повторите сценарий.
liveness_session_expired
Время действия liveness-сессии истекло.
Начните новую сессию. Рекомендуется отображать таймер обратного отсчёта на UI, чтобы пользователь успел завершить проверку.
liveness_qr_expired
Время жизни QR-кода для liveness истекло.
Сформируйте новый QR-код и предложите пользователю повторить сканирование.
liveness_error
Неожиданная ошибка на этапе liveness-проверки.
Предложите пользователю повторить попытку. При повторяющихся ошибках обратитесь в поддержку с requestId.
device_error
Камера недоступна или устройство не поддерживается.
Отобразите пользователю сообщение с просьбой разрешить доступ к камере в настройках браузера или использовать другое устройство.
iin_not_found
ИИН не найден в государственной базе ГБДФЛ.
Проверьте корректность переданного ИИН (12 цифр). Убедитесь, что пользователь является резидентом РК и зарегистрирован в ГБДФЛ.
auth_liveness_step_cancelled
Пользователь нажал «Отменить» на этапе liveness-проверки.
Отобразите пользователю сообщение о прерванной операции и предложите начать сценарий заново.
server_error
Внутренняя ошибка сервера.
Отобразите пользователю сообщение о временной ошибке и предложите повторить попытку позже.
network_connectivity_error
Сетевая ошибка во время сценария.
Проверьте стабильность соединения. Отобразите пользователю сообщение об ошибке сети и предложите повторить попытку.
2.4. Проверка одноразового кода
На этапе проверки одноразового (единовременного) кода используются следующие redirect-ошибки.
sms_limit_exceeded
Исчерпано количество попыток отправки SMS с кодом.
Отобразите пользователю сообщение об исчерпании попыток. Предложите начать сценарий заново после небольшой паузы.
sms_code_attempts_exceeded
Исчерпано количество попыток ввода SMS-кода.
Отобразите пользователю сообщение об исчерпании попыток. Предложите начать сценарий заново и запросить новый код.
auth_sms_code_cancelled
Пользователь нажал «Отменить» на этапе ввода одноразового кода.
Отобразите пользователю сообщение о прерванной операции и предложите начать сценарий заново.
2.5. Согласие на доступ к данным
На этапе предоставления пользователем согласия на доступ к его данным используются следующие redirect-ошибки.
access_denied
Пользователь отклонил согласие на доступ к его данным.
Отобразите пользователю сообщение о том, что без предоставления согласия авторизация невозможна. При необходимости предложите начать сценарий заново.
2.6. Выпуск облачной ЭЦП и подписание
На этапе выпуска облачной ЭЦП / подписания документов используются следующие redirect-ошибки.
esign_is_blocked
Использование облачной ЭЦП недоступно.
Проверьте статус облачной ЭЦП пользователя. Для разблокировки необходимо обратиться в НУЦ РК.
esign_is_blocked_and_ready_to_reset
ЭЦП заблокирована, но готова к сбросу.
Предложите пользователю пройти процедуру сброса ЭЦП. После успешного сброса сценарий можно повторить.
esign_error
Ошибка при подписании документа.
Предложите пользователю повторить попытку. При повторяющихся ошибках обратитесь в поддержку с requestId.
2.7. Ввод БИН организации
Актуально для scope organization_esign. На этапе ввода БИН организации используются следующие redirect-ошибки.
auth_bin_step_cancelled
Пользователь нажал «Отменить» на этапе ввода БИН.
Отобразите пользователю сообщение о прерванной операции и предложите начать сценарий заново.
2.8. Получение токена доступа
На этапе вызова метода POST /oauth2/token используются следующие коды ошибок.
HTTP 400
INVALID_REQUEST
Некорректный запрос — не передан grant_type или другой обязательный параметр.
Проверьте наличие и формат обязательных параметров: grant_type, code, redirect_uri, client_id, client_secret.
INVALID_GRANT
Неправильный redirectUri, неправильный или повторно используемый код авторизации.
Код авторизации одноразовый — используйте его только один раз сразу после получения. Если код уже использован или истёк, запустите сценарий заново.
UNSUPPORTED_GRANT_TYPE
Значение grant_type отличное от authorization_code.
Используйте только grant_type=authorization_code. Другие типы в данном методе не поддерживаются.
HTTP 401
INVALID_CLIENT
Неверный client_id или client_secret.
Проверьте правильность client_id и client_secret в настройках вашего приложения на платформе. Убедитесь, что учётные данные не были сброшены или изменены.
HTTP 500
INTERNAL_ERROR
Внутренняя ошибка сервера.
Повторите запрос. При повторяющихся ошибках обратитесь в поддержку, передав requestId из ответа.
2.9. Получение отчёта по сессии
Метод GET /v1/auth/sessions/{sessionId}/report/download работает асинхронно. Пока отчёт формируется, сервис возвращает код SESSION_REPORT_NOT_READY.
HTTP 404
SESSION_REPORT_NOT_READY
Отчёт по сессии ещё не сформирован (асинхронная генерация).
Реализуйте polling с интервалом 1–2 секунды. Рекомендуемый таймаут ожидания — не более 30 секунд. По истечении таймаута обратитесь в поддержку с sessionId.
3. Сервис сопостовления фототзоборажения
В этом разделе собраны ошибки для методов POST /verify/sync, POST /verify/async, GET /verify/async/{verificationId}, GET /personal-data/{verificationId}, GET /report/{verificationId}.
HTTP 400
JWS_INVALID
POST /verify/sync
JWS-подпись невалидна, или iin/bin/consentType в payload не совпадают с параметрами запроса.
Проверьте формирование JWS: payload должен содержать актуальные данные текущего запроса. Убедитесь, что значения iin, bin и consentType в payload совпадают с параметрами вызова.
SCORE_LESS_THRESHOLD
GET /personal-data/{verificationId}
Результат биометрического сопоставления ниже порогового значения вендора.
Предложите пользователю повторить верификацию при хорошем освещении. Не раскрывайте числовое значение score пользователю — отображайте только факт неудачи.
HTTP 403
Organizations feature IDENTITY is not active
Все /verify/, /personal-data/, /report/*
У организации не активирована аккредитация IDENTITY или клиент не зарегистрирован как Identity-клиент.
Обратитесь к администратору платформы для активации аккредитации IDENTITY.
Organizations feature IDENTITY_DATA is not active
Только GET /personal-data/{verificationId}
У организации не активирована аккредитация IDENTITY_DATA.
Требуется отдельный запрос на активацию аккредитации IDENTITY_DATA. Обратитесь к администратору платформы.
HTTP 500
GOV_SERVICE_UNAVAILABLE
POST /verify/async, GET /verify/async/{verificationId}
Государственные базы данных (КДП / ГБДФЛ) временно недоступны.
Повторите запрос позже. Сохраняйте requestId для обращения в поддержку, если ошибка не исчезает.
4. Организации, полномочия и отзыв доступа
В этом разделе собраны ошибки для управления организациями, матрицей полномочий и отзыва доступа.
HTTP 400
EMPLOYEE_IS_NOT_IN_ORGANIZATION
Сотрудник не найден в составе организации — не существует или деактивирован.
Проверяйте актуальный список сотрудников через GET-запрос перед выполнением операций.
GBDUL_ORGANIZATION_NOT_FOUND
Организация по переданному БИН не найдена в реестре ГБДЮЛ.
Проверьте корректность БИН (12 цифр). Если БИН верный, пользователю следует обратиться в ЦОН для актуализации данных организации.
GBDUL_IIN_NOT_LEADER
ИИН не является руководителем данной организации по данным ГБДЮЛ.
Убедитесь, что пользователь официально назначен руководителем организации в государственном реестре ГБДЮЛ.
GBDUL_ORGANIZATION_HAS_DIFFERENT_LEADER
В ГБДЮЛ у организации зарегистрирован другой руководитель.
Актуализируйте данные руководителя в государственном реестре через ЦОН.
ACCESS_ALREADY_REVOKED
Попытка отозвать уже отозванный доступ по сессии.
Обрабатывайте такой ответ как успешный — доступ уже был отозван ранее.
HTTP 403
EMPLOYEE_PERMISSION_DENIED
У сотрудника нет прав для выполнения данной операции.
Проверьте роль и разрешения сотрудника. Рекомендуется скрывать недоступные действия на UI до отправки запроса.
HTTP 409
IIN_ALREADY_EXISTS
Сотрудник с таким ИИН уже существует в данной организации.
Перед добавлением проверьте список сотрудников через GET-запрос. Не создавайте дубликаты.
IIN_ATTACHED_TO_ANOTHER_ORGANIZATION
ИИН уже привязан к другой организации.
Сотрудник должен быть деактивирован в предыдущей организации перед добавлением в новую.
EMPLOYEE_MISSING_SIGN_AUTHORITY_OR_PERMISSIONS
У сотрудника не задана ни матрица полномочий, ни разрешения — обязательно должно быть настроено одно из двух.
Назначьте сотруднику матрицу полномочий или разрешения. Рекомендуется валидировать наличие настроек на UI до отправки запроса.
Last updated