Ошибки

Этот раздел описывает общие принципы обработки ошибок во всех API платформы.

Уровни ошибок

Ошибки можно условно разделить на три слоя:

• HTTP‑уровень — коды ответа (4xx, 5xx);
• уровень API — структура JSON‑ошибки (поля title, message, error, error_description и т.п.);
• бизнес‑уровень — доменные статусы и коды (статусы заявок, верификаций, результаты проверок).

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

• анализировать и HTTP‑код, и тело ответа;
• логировать ключевые поля ошибки и идентификаторы запросов.

HTTP‑коды

Типичные коды:

• 200 OK — успешный запрос;
• 400 Bad Request — ошибка валидации или неправильный формат данных;
• 401 Unauthorized — неверный или отсутствующий токен;
• 403 Forbidden — недостаточно прав;
• 404 Not Found — ресурс не найден;
• 429 Too Many Requests — превышены лимиты;
• 5xx — внутренние ошибки сервисов (временные или постоянные).

Конкретный набор кодов и интерпретацию для каждого сервиса смотрите в соответствующих разделах.

Формат ошибок в OCR

Пример бизнес‑ошибки из OCR:

{
  "title": "DocumentNotRecognized",
  "message": "Невозможно произвести извлечение данных из документа."
}

В спецификации приведена таблица кодов:

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

Подробнее: Продукты → OCR → Ошибки и API Reference → OCR API → Errors.

Формат ошибок в Verification

Для Verification:

• используются HTTP‑коды (400, 401, 403, 404, 429, 500 и др.);
• в теле ответа и callback‑уведомлений приходят статусы и описания ошибок по каждой проверке.

Примеры и подробности — в разделе Продукты → Verification → Ошибки и коды ответов.

Ошибки авторизации (OAuth 2.0)

При работе с токен‑сервисом и Mobile ID могут возвращаться стандартные ошибки OAuth:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Типичные значения error:

• invalid_client
• invalid_grant
• invalid_scope
• unauthorized_client

Ретраи и устойчивость

• для временных технических ошибок (5xx, сетевые таймауты) допускается реализация ретраев с экспоненциальной задержкой;
• для бизнес‑ошибок (4xx, доменные статусы) ретраи обычно не имеют смысла и требуется бизнес‑обработка
  (исправление данных, запрос дополнительных документов и т.п.).

Общие рекомендации по ретраям и идемпотентности см. также в разделе
«Начало работы → Ошибки и ретраи».