Коды ошибок
Эта страница является единственным источником достоверной информации по обработке ошибок. Коды ошибок, специфичные для SDK, задокументированы на странице Обработка ошибок каждого SDK; данная страница охватывает ошибки на уровне API-контракта.
Коды состояния HTTP
| Код | Значение | Область применения |
|---|---|---|
200 OK | Запрос выполнен успешно. | Все контракты. |
201 Created | Ресурс создан (редко; большинство операций создания возвращают 200). | Контракт API. |
400 Bad Request | Payload некорректен или отсутствуют обязательные поля. В теле ответа указаны проблемные поля. | Все контракты. |
401 Unauthorized | Аутентификация отсутствует, просрочена или недействительна. | Все контракты. |
403 Forbidden | Аутентификация действительна, но тенант не включён для запрошенного ресурса (например, вызов возможности, не входящей в ваш APIKEY). | Web & SDK, API. |
404 Not Found | Ресурс не существует или не принадлежит аутентифицированному тенанту. | Все контракты. |
409 Conflict | Ресурс существует, но находится не в том состоянии для данной операции (например, получение документов из процесса, который ещё выполняется). | Web & SDK, API. |
410 Gone | Ресурс существовал, но был удалён согласно политике хранения (эндпоинты получения документов), либо процесс существует, но завершился с ошибкой — см. Получение процесса. | Эндпоинты получения документов; API Get Process. |
429 Too Many Requests | Превышен лимит частоты запросов. Повторите попытку с экспоненциальной задержкой. | Все контракты. |
5xx | Ошибка платформы. Повторите попытку с задержкой; если проблема не исчезает, обратитесь в поддержку с телом ответа и временной меткой. | Все контракты. |
Ошибки аутентификации (401)
| Причина | Симптом |
|---|---|
| Неверный закрытый ключ (assertion подписан не тем ключом) | 401, Authentication failed (1.2.21) |
aud не совпадает с URL среды | 401 |
Claim exp в прошлом | 401, Authentication failed |
Неподдерживаемый алгоритм (используйте RS256) | 401 |
| Смешение учётных данных sandbox / production | 401, даже если учётные данные выглядят корректно |
Отсутствует заголовок APIKEY (только контракт API) | 401 |
Недействительный x-api-key (только Magic Link) | 401 |
См. Аутентификация > Типичные ошибки для полного контрольного списка устранения неполадок.
Результаты на уровне возможностей (200 с отрицательным результатом)
Статус 200 OK не означает, что пользователь прошёл верификацию — он означает, что платформа завершила работу. Решение на уровне пользователя содержится в теле ответа, а не в HTTP-статусе:
| Поле | Отрицательное значение | Место нахождения |
|---|---|---|
process.result | PROCESS_RESULT_FAILED | Web & SDK |
process.authenticationInfo.livenessResult | NO | Web & SDK |
liveness | 2 | API |
unicoId.result | no | API |
data.result.status | not_verified | Magic Link |
Политика повторных попыток
| Статус | Повторять? | Как |
|---|---|---|
5xx | Да | Экспоненциальная задержка (1 с, 2 с, 4 с, 8 с, …). Ограничьте 5 попытками. |
429 | Да | Соблюдайте заголовок Retry-After, если он присутствует; иначе используйте экспоненциальную задержку. |
4xx (другие) | Нет | Запрос некорректен. Исправьте входные данные перед повторной попыткой. |
401 | Условно | Обновите токен доступа один раз. Если новый запрос также возвращает 401, проблема структурная — не повторяйте попытку. |
Платформа IDCloud в настоящее время не предоставляет механизм ключа идемпотентности для эндпоинтов создания. Будьте осторожны при повторных попытках POST /client/v1/process или POST /processes/v1 — сетевая ошибка при 5xx может означать, что операция фактически выполнилась на сервере, и повторная попытка создаст дублирующий процесс. В случае сомнений получите список последних процессов по вашему внутреннему correlation ID перед повторной попыткой.
Где находятся ошибки SDK
Каталоги ошибок Web SDK, Android SDK, iOS SDK и Flutter SDK задокументированы на специальной странице Обработка ошибок каждого SDK:
- Web SDK > Обработка ошибок
- Android SDK > Обработка ошибок
- iOS SDK > Обработка ошибок
- Flutter SDK > Обработка ошибок
Они охватывают ошибки на стороне устройства (запрет доступа к камере, тайм-аут захвата, недоступность сети на устройстве) — в отличие от ошибок на стороне API, задокументированных здесь.