KYC ПЛАТФОРМА

Ошибки и ретраи

Все API МТС KYC платформы (KYC, Mobile ID, Verification, OCR)
возвращают ошибки через HTTP‑коды и JSON‑тело ответа.

Общие принципы ошибок

Типичные группы:

  • 4xx — ошибки на стороне клиента:
  • некорректные параметры запроса;
  • отсутствие обязательных полей;
  • неверный токен или права доступа.
  • 5xx — ошибки на стороне сервиса:
  • временные сбои инфраструктуры;
  • ошибки внутренних компонентов.

Рекомендуется:

  • всегда анализировать и HTTP‑код, и тело ответа;
  • логировать код, текст ошибки и корреляционный идентификатор (если есть).

Примеры по продуктам

KYC

В KYC используются собственные справочники статусов и ошибок:

  • статусы заявок и идентификаций описаны в разделе
    «Продукты → KYC → Справочники → Статусы / Ошибки»;
  • при ошибках валидации или нарушении бизнес‑правил возвращаются коды с описаниями.

Рекомендуется:

  • различать технические и бизнес‑ошибки;
  • для бизнес‑ошибок корректно обрабатывать ситуацию на уровне UI/процессов.

Verification

В Verification ошибки делятся на:

  • HTTP‑коды (400, 401, 403, 404, 429, 500 и т.д.);
  • бизнес‑ошибки и статусы в теле ответа/Callback (см.
    «Продукты → Verification → Ошибки и коды ответов»).

Примеры проблем:

  • некорректный набор данных для конкретной проверки;
  • некорректная настройка completionStrategy или modules;
  • недоступность внешних источников (СМЭВ, скоринговые сервисы).

OCR

OCR имеет явные бизнес‑ошибки, например:

  • DocumentNotRecognized — «Невозможно произвести извлечение данных из документа.»

А также таблицу кодов:

  • системные (500 system_error, 500 internal_error, 500 empty_request_body, …);
  • бизнес‑ошибки (400 photos_not_found, 400 empty_or_correct_type_format,
    400 document_type_not_found и др.).

Подробнее см. разделы:

  • Продукты → OCR → Ошибки;
  • API Reference → OCR API → Errors.

Mobile ID

Mobile ID использует стандартные ошибки OAuth 2.0:

  • invalid_client, invalid_grant, invalid_scope и т.д.;
  • ошибки при вызове /authorize, /token, /userinfo.

Примеры приведены в API Reference → Mobile ID API.

Ретраи и идемпотентность

  1. Когда можно повторять запрос
  2. при сетевых ошибках;
  3. при ответах 5xx (особенно 500, 502, 503, 504);

  4. при явно обозначенных временных ограничениях (429 Too Many Requests).

  5. Когда ретраи опасны

  6. для операций, создающих сущности (заявителей, идентификации, batch‑запросы на Verification),
    важно обеспечивать идемпотентность:

    • использовать внешние идентификаторы (applicantExternalId, verificationExternalId);
    • при повторном вызове с тем же идентификатором проверять, не был ли запрос уже обработан.

  7. Рекомендации по стратегии

  8. использовать экспоненциальную задержку между повторными попытками;
  9. ограничивать максимальное число ретраев;
  10. для callback‑обработчиков на вашей стороне также реализовать повторяемость
    (чтобы повторная доставка callback не приводила к дублированию операций).

Логирование и мониторинг

  • логируйте:
  • время запроса;
  • HTTP‑код;
  • тело ошибки;
  • ключевые идентификаторы (applicantExternalId, verificationExternalId и т.п.);
  • настраивайте алерты для частых или критичных ошибок (по кодам/статусам);
  • используйте эти данные для настройки ретраев и улучшения UX.