Обработка ошибок¶

Каждая ошибка возвращается как JSON с единственным полем message, описывающим что пошло не так:

{
  "message": "externalUserId is required"
}

HTTP-код — основной сигнал. Тело — для логирования и показа пользователю текста, который вы сами решите.

Коды статусов¶

Код	Категория	Что значит	Что делать клиенту
`200 OK`	Успех	Запрос выполнен.	Обработайте тело ответа.
`201 Created`	Успех	Ресурс создан.	То же что 200; новый ресурс в теле.
`202 Accepted`	Успех	Запрос принят на асинхронную обработку (например, ingest вебхука, создание hosted-сессии верификации).	Считайте успехом; наблюдайте через `GET` или ждите вебхук.
`400 Bad Request`	Клиент	Запрос некорректный или отсутствует обязательное поле. `message` описывает что не так.	Исправьте запрос; не повторяйте тот же payload.
`401 Unauthorized`	Клиент	`X-Api-Key` / `X-Api-Secret` отсутствуют или не совпадают с активной парой.	Проверьте credentials. Если вчера работали — проверьте портал продукта, ключ мог быть деактивирован.
`403 Forbidden`	Клиент	Credentials валидные, но ваш продукт не имеет доступа к этому ресурсу (например, заявитель из другого продукта).	Остановитесь и проверьте. Повтор не поможет.
`404 Not Found`	Клиент	Заявитель / уровень / документ из URL не существует для вашего продукта.	Проверьте `externalUserId` / id; возможно нужно сначала создать ресурс.
`422 Unprocessable Entity`	Клиент	Запрос синтаксически валиден, но семантически отклонён — например, вызов `/verify` для заявителя без подходящего verification level.	Исправьте данные и повторите.
`429 Too Many Requests`	Клиент	Превышен per-IP rate limit (в частности, auth-эндпойнты ограничены 20/мин). Ответ содержит заголовок `Retry-After` со сколько секунд ждать.	Подождите `Retry-After` и повторите. Если видите часто — добавьте client-side rate limiting.
`500 Internal Server Error`	Сервер	Неожиданная серверная ошибка.	Безопасно повторить идемпотентные запросы после паузы. Постоянно? Свяжитесь с поддержкой.
`502 Bad Gateway` / `503 Service Unavailable` / `504 Gateway Timeout`	Сервер	Транзиентная инфраструктурная ошибка, часто во время деплоев.	Повторите с экспоненциальным backoff (~1 с, 2 с, 4 с, 8 с, кэп ~30 с).

API сейчас не возвращает 409 Conflict. Повторное создание заявителя через POST /v1/applicants идемпотентно по externalUserId — вы получите 200 OK с существующим заявителем, не конфликт.

Идемпотентность и повторы¶

GET, DELETE, PUT идемпотентны — безопасно повторять при любой 5xx или сетевой ошибке.
POST /v1/applicants идемпотентен по externalUserId — повторная отправка того же externalUserId возвращает существующего заявителя.
Остальные POST запросы не автоматически идемпотентны. Если боитесь дубликатов от retry-шторма — храните client-side хеш (endpoint + payload) и не отправляйте повторно.

Пример ошибки валидации¶

Отправка запроса создания без externalUserId:

{
  "message": "externalUserId is required"
}

Если ошибок несколько — ответ опишет первую найденную; API останавливается на первой проблеме, а не возвращает список. Исправьте и повторите.

Что логировать¶

Для каждого non-2xx ответа логируйте:

HTTP-метод и путь, который вызывали.
Полное тело ответа.
Точный UTC timestamp запроса.
Для 429 — значение Retry-After.

Не логируйте тела, содержащие документы, selfie или PII. Не логируйте заголовок X-Api-Secret.

Обращение в поддержку¶

Если статус действительно неожиданный (например, 500 на запросе, который вчера работал), откройте тикет с:

Полным методом + URL запроса (только path — обрежьте query strings с персональными данными).
Точным UTC timestamp.
externalUserId заявителя, если применимо.
1–2 предложениями: что вы ждали vs что получили.

Не вставляйте API-ключи или PII заявителей в тикет.