Коды ошибок

1. HTTP-статусы ответа для ошибок

Используемые HTTP-статусы ответа для ошибок:

HTTP response status

 - 400 - некорректный запрос.
 - 401 - авторизация не пройдена . 
 - 403 - используется для обозначения того, что клиент не имеет необходимых разрешений для ресурса или запрос понятен серверу, но сервер отказывается его авторизовать.
 - 404 - запрошен ресурс, который не реализован, или ресурс, который не определен в спецификации.
 - 405 - попытка получить доступ к ресурсу с помощью метода, который не поддерживается
 - 406 - указывает на то, что сервер не может выдать ответ, соответствующий списку допустимых значений, определенному в заголовках запроса.
 - 429 - превышен лимит запросов.
 - 500 - внутренняя ошибка сервера.

2. Коды ошибок по этапам

2.1. Получение URL-адреса для перенаправления пользователя

На этапе получения URL-адреса для перенаправления пользователя (вызов метода POST /v1/auth/generate-user-url) используются следующие коды ошибок:

HTTP 400

- `FIELD_MISSING` - отсутствует обязательный параметр.
- `FIELD_INVALID` - указано некорректное значение.
- `IIN_BLOCKED` - ИИН пользователя заблокирован. Клиент исчерпал 4 (четыре) попытки прохождения liveness-проверки в пределах одной сессии. Клиенту необходимо подождать 15 минут (по умолчанию), чтобы повторить попытку.
- `IIN_NOT_FOUND` - ИИН не найден.
- `PHONE_BELONGS_TO_ANOTHER_IIN_IN_BMG` - номер телефона принадлежит другому ИИН в базе пользователей ЦОИД и в Базе мобильных граждан (БМГ). Возможные причины:
     • Номер телефона ранее был зарегистрирован на другого человека
     • Абонент переоформил номер на себя, но данные в БМГ ещё не обновлены
     • Ошибка при вводе ИИН или номера телефона.
Рекомендации для клиента:
     • Проверить, правильно ли указан ИИН и номер телефона.
     • Убедиться, что номер телефона оформлен именно на клиента.
- `NO_ACTIVE_CONTRACT` - отсутствует активный договор с организацией.
- `GBDFL_PERSON_UNDER_18_YEARS` - пользователь младше 18 лет.
- `INVALID_SCOPES` - некорректное значение области доступа (scopes) или нет прав на использование указанной области доступа (scopes).
- `INVALID_REDIRECT_URI` - некорректный адрес переадресации. Адрес переадресации должен совпадать с одним из URI переадресации, указанных при регистрации приложения на Платформе.
- `ESIGN_BLOCKED` - использование облачной ЭЦП недоступно.
- 'ESIGN_UNSIGNED_DOCUMENT' - документ не подписан.
- 'GBDFL_PERSON_INVALID_STATUS' – недопустимый статус пользователя.
Возможные значения статуса:
     • Capable – статус дееспособности.
     • Imprisoned – статус осуждения.
     • Missing – статус «пропавший без вести».
Рекомендации для клиента:
     • Клиенту следует обратиться в ЦОН или соответствующие государственные органы для уточнения своего статуса.

HTTP 500

    - `NO_ACTIVE_CONTRACT_WITH_VENDOR` - для организации не определен вендор, который должен использоваться для биометрической верификации пользователя.
    - `GOV_SERVICE_UNAVAILABLE` - не доступны эталонные (государственные) базы данных.
    - `DOCUMENT_NOT_FOUND` - не найдены данные документа, удостоверяющего личность в эталонных (государственных) базах данных.
 Возможные причины ошибки:
    • Клиент не является резидентом Республики Казахстан.
    • Ошибка или отсутствие данных в государственных системах.
Рекомендации для клиента:
    •Клиенту следует обратиться в ЦОН или соответствующие государственные органы для уточнения своего статуса.
    - `INTERNAL_ERROR` - внутренняя ошибка сервера. Необходимо повторно отправить запрос.
    - `DOCUMENT_NOT_FOUND_IN_TEST_DB` - не найдены данные документа, удостоверяющего личность в тестовой базе данных. Данный код ошибки используется только на тестовом окружении.

2.2. Подтверждение ИИН, по которому проводится аутентификация личности

На этапе подтверждения пользователем своего ИИН используются следующие коды ошибок:

Redirect errors

- `auth_iin_step_cancelled` - пользователь прекратил процесс (нажал кнопку "Отменить") на этапе подтверждения своего ИИН.
- `unauthorized` - некоррекнтый URL-адреса для перенаправления пользователя или время действия ссылки истекло.
- `server_error` - внутренняя ошибка сервера.
- `network_connectivity_error` - сетевая ошибка.

Если на данном этапе происходит ошибка, то Пользователь будет перенаправлен на указанный при получении URL-адреса для перенаправления пользователя (вызов метода POST /v1/auth/generate-user-url) redirectUri, с указанием кода ошибки, по следующему шаблону:

[redirectUri]?errorCode=[error code]&state=[state]

2.3. Проведение liveness-проверки лица и процедуры сопоставления фотоизображения

На этапе проведения liveness-проверки лица и процедуры сопоставления фотоизображения используются следующие коды ошибок:

Redirect errors

- `gbdfl_photo_not_found` - в эталонной (государственной) базе данных не найдены фото для сверки.
- `gbdfl_face_not_matched` - не пройдена процедура сопоставления фотоизображения с фото из эталонной (государственной) базы данных.
Возможные причины:
   •Документ, удостоверяющий личность был получен 10 и более лет назад, а процедура сопоставления фотоизображения проводится сейчас. За это время внешность клиента могла измениться.Рекомендация: Клиенту необходимо обновить удостоверение личности. 
   •Неправильное освещение или ракурс – лицо плохо освещено, закрыто посторонними предметами или находится под неправильным углом, что мешает корректному распознаванию  
- `gov_service_unavailable` - не доступны эталонные (государственные) базы данных.
- `gbdfl_person_under_18_years` - пользователь младше 18 лет.
- `liveness_attempts_exceeded` -  исчерпано количество доступных попыток прохождения  liveness-проверки.
 Возможные причины:
   •Неправильное освещение или ракурс – лицо плохо освещено, закрыто посторонними предметами или находится под неправильным углом, что мешает корректному распознаванию.
   •Технические сбои – ошибки на стороне сервиса или устройства пользователя (например, сбои телефона, неподдерживаемый браузер).
   •Использование неподходящих изображений – попытка пройти проверку с фотографией, видео или сторонними материалами.
 Рекомендация: проверить условия освещения, использовать поддерживаемые устройства и программное обеспечение.
- `iin_not_found` - ИИН не найден.
- `auth_liveness_step_cancelled` - пользователь прекратил процесс (нажал кнопку "Отменить") на этапе liveness-проверки лица.
- `server_error` - внутренняя ошибка сервера.
- `network_connectivity_error` - сетевая ошибка.

Если на данном этапе происходит ошибка, то Пользователь будет перенаправлен на указанный при получении URL-адреса для перенаправления пользователя (вызов метода POST /v1/auth/generate-user-url) redirectUri, с указанием кода ошибки, по следующему шаблону:

[redirectUri]?errorCode=[error code]&state=[state]

2.4. Проверка одноразового (единовременного) кода

На этапе проверки одноразового (единовременного) кода используются следующие коды ошибок:

Redirect errors

- `sms_limit_exceeded` - исчерпано количество доступных попыток отправки SMS с кодом.
- `sms_code_attempts_exceeded` - исчерпано количество доступных попыток ввода кода.
- `auth_sms_code_cancelled` - пользователь прекратил процесс (нажал кнопку "Отменить") на этапе ввода одноразового (единовременного) кода.

Если на данном этапе происходит ошибка, то Пользователь будет перенаправлен на указанный при получении URL-адреса для перенаправления пользователя (вызов метода POST /v1/auth/generate-user-url) redirectUri, с указанием кода ошибки, по следующему шаблону:

[redirectUri]?errorCode=[error code]&state=[state]

2.5. Предоставление пользователем согласия на доступ к его данным

На этапе предоставления пользователем согласия на доступ к его данным используются следующие коды ошибок:

Redirect errors

- `access_denied` - пользователь отклонил согласие на доступ к его данным.

Если Пользователь отклоняет согласие на доступ к его данным, то Пользователь будет перенаправлен на указанный при получении URL-адреса для перенаправления пользователя (вызов метода POST /v1/auth/generate-user-url) redirectUri, с указанием кода ошибки, по следующему шаблону:

[redirectUri]?errorCode=[error code]&state=[state]

2.6. Выпуск облачной ЭЦП / подписание документов облачной ЭЦП

На этапе выпуска облачной ЭЦП / подписания документов облачной ЭЦП используются следующие коды ошибок:

Redirect errors

- `esign_is_blocked` -  использование облачной ЭЦП недоступно.
- `esign_error` - ошибка подписания документа.

Если на данном этапе происходит ошибка, то Пользователь будет перенаправлен на указанный при получении URL-адреса для перенаправления пользователя (вызов метода POST /v1/auth/generate-user-url) redirectUri, с указанием кода ошибки, по следующему шаблону:

[redirectUri]?errorCode=[error code]&state=[state]

2.7. Получение результата аутентификации/токена доступа

На этапе вызова метода POST /oauth2/token используются следующие коды ошибок:

HTTP 400

- `INVALID_REQUEST` - некорректный запрос.
- `INVALID_GRANT` - предоставлен неправильный redirectUri, неправильный или повторно используемый код авторизации.
- `UNSUPPORTED_GRANT_TYPE` - указано значение параметра grant_type отличное от authorization_code.

HTTP 500

- `INTERNAL_ERROR` - внутренняя ошибка сервера.