# Коды ошибок

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

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

<pre data-title="HTTP response status" data-overflow="wrap"><code> - 400 - некорректный запрос.
 - 401 - авторизация не пройдена . 
<strong> - 403 - используется для обозначения того, что клиент не имеет необходимых разрешений для ресурса или запрос понятен серверу, но сервер отказывается его авторизовать.
</strong> - 404 - запрошен ресурс, который не реализован, или ресурс, который не определен в спецификации.
 - 405 - попытка получить доступ к ресурсу с помощью метода, который не поддерживается
 - 406 - указывает на то, что сервер не может выдать ответ, соответствующий списку допустимых значений, определенному в заголовках запроса.
 - 429 - превышен лимит запросов.
 - 500 - внутренняя ошибка сервера.
</code></pre>

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

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

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

<pre data-title="HTTP 400" data-overflow="wrap"><code>- `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' – недопустимый статус пользователя.
Возможные значения статуса:
<strong>     • Capable – статус дееспособности.
</strong>     • Imprisoned – статус осуждения.
     • Missing – статус «пропавший без вести».
Рекомендации для клиента:
     • Клиенту следует обратиться в ЦОН или соответствующие государственные органы для уточнения своего статуса.


</code></pre>

{% code title="HTTP 500" overflow="wrap" %}

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

{% endcode %}

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

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

{% code title="Redirect errors" overflow="wrap" %}

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

{% endcode %}

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

`[redirectUri]?errorCode=[error code]&state=[state]`
{% endhint %}

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

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

{% code title="Redirect errors" overflow="wrap" %}

```
- `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` - сетевая ошибка.
```

{% endcode %}

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

`[redirectUri]?errorCode=[error code]&state=[state]`
{% endhint %}

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

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

{% code title="Redirect errors" overflow="wrap" %}

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

{% endcode %}

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

`[redirectUri]?errorCode=[error code]&state=[state]`
{% endhint %}

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

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

{% code title="Redirect errors" overflow="wrap" %}

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

{% endcode %}

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

`[redirectUri]?errorCode=[error code]&state=[state]`
{% endhint %}

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

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

{% code title="Redirect errors" overflow="wrap" %}

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

{% endcode %}

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

`[redirectUri]?errorCode=[error code]&state=[state]`
{% endhint %}

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

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

{% code title="HTTP 400" overflow="wrap" %}

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

{% endcode %}

{% code title="HTTP 500" overflow="wrap" %}

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

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.npck.kz/servisy-coid/kody-oshibok.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.