> For the complete documentation index, see [llms.txt](https://docs.npck.kz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.npck.kz/servisy-coid/kody-oshibok.md). # Коды ошибок ## Коды ошибок На странице собраны коды ошибок для сценариев аутентификации, биометрии, Identity API и операций с организациями. ### 1. HTTP-статусы ответа для ошибок Используемые HTTP-статусы ответа для ошибок: | HTTP-статус | Описание | | ----------- | --------------------------------------------------- | | 400 | Некорректный запрос. | | 401 | Авторизация не пройдена. | | 403 | Клиент не имеет необходимых разрешений для ресурса. | | 404 | Запрошенный ресурс не найден. | | 405 | Метод не поддерживается. | | 406 | Сервер не может выдать ответ в запрошенном формате. | | 429 | Превышен лимит запросов. | | 500 | Внутренняя ошибка сервера. | {% hint style="info" %} Ошибки пользовательских шагов (liveness, OTP, ЭЦП, согласие) передаются через redirect-механизм OAuth2 Authorization Code Flow. Пользователь перенаправляется на **redirectUri** с кодом ошибки в query-параметре по шаблону: **\[redirectUri]?errorCode=\[error code]\&state=\[state]** Эти ошибки не возвращаются напрямую в теле ответа, поэтому их следует обрабатывать на стороне фронтенда при получении управления обратно на **redirectUri**. {% endhint %} ### 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. Получение отчёта по сессии {% hint style="info" %} Метод **GET /v1/auth/sessions/{sessionId}/report/download** работает асинхронно. Пока отчёт формируется, сервис возвращает код **SESSION\_REPORT\_NOT\_READY**. {% endhint %} **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** | Код ошибки | Endpoint | Причина | Что делать | | ---------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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** | Сообщение | Endpoint | Причина | Что делать | | -------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | | 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** | Код ошибки | Endpoint | Причина | Что делать | | ------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | 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 до отправки запроса. |