Перейти к содержимому
Справочник API Получить API-ключи

Интеграция · Глава 9

Ошибки

Каждая ошибка имеет одинаковую JSON-структуру и стабильный машиночитаемый code. Стройте обработку ошибок на HTTP-статусе и code, а не на тексте сообщения.

4 мин чтения

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

{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid.",
    "fields": {
      "external_id": ["The external id field is required."]
    },
    "request_id": "req_01m6yyj5gq0x3c7d2n8v5kp4rt"
  }
}
Поле Примечание
code Стабильный код ошибки из таблицы ниже
message Понятное человеку пояснение на английском. Может меняться; не разбирайте его
fields Только при validation_failed: имя поля → список сообщений. Опирайтесь на имя поля, а не на текст
request_id Совпадает с заголовком ответа X-Request-Id. Указывайте его при обращении в поддержку

HTTP-статусы

Статус Значение
200 / 201 Успех / создано
202 Принято: действие продолжается в фоне (удаление заявителя, RED, ожидающий второго проверяющего)
400 Запрос составлен неверно или не прошёл валидацию
401 API-ключ отсутствует, неизвестен или отозван
403 Ключ действителен, но действие для этого аккаунта запрещено
404 Не найдено — или принадлежит другому аккаунту либо окружению
409 Конфликт с текущим состоянием
413 Файл слишком большой
422 Запрос корректен, но не может быть выполнен
429 Достигнут лимит запросов или лимит тарифа
500 Непредвиденная ошибка на нашей стороне
503 Зависимый сервис временно недоступен

Коды ошибок

HTTP code Когда Что делать
400 bad_request Битый JSON, неверный формат Idempotency-Key, недопустимый параметр Исправить запрос
400 validation_failed Поле отсутствует или некорректно; см. fields Исправить указанные поля
401 unauthenticated API-ключ отсутствует, неизвестен или отозван Проверить заголовок Authorization и ключ
403 forbidden Аккаунт неактивен Обратиться в поддержку
403 tenant_not_verified Боевой ключ используется до верификации бизнеса Завершить верификацию бизнеса — см. Тестовый и боевой режимы
404 not_found ID не существует, принадлежит другому аккаунту или окружению, либо неверен путь Проверить ID и окружение ключа
409 conflict Действие не соответствует текущему состоянию (см. ниже) Прочитать текущее состояние и действовать по нему
409 idempotency_conflict Тот же Idempotency-Key использован с другим запросом Для нового запроса использовать новый ключ
413 file_too_large Загруженный файл превышает лимит Отправить файл меньшего размера
422 unprocessable Неизвестный или удалённый flow; больше 10 вебхук-эндпоинтов Исправить значение или удалить эндпоинт
429 rate_limited Слишком много запросов Подождать Retry-After секунд и повторить
429 plan_limit_reached Месячный лимит боевых проверок по тарифу исчерпан Дождаться следующего месяца или сменить тариф
500 internal_error Непредвиденная ошибка Повторить с задержкой; если не проходит, обратиться в поддержку с request_id
503 aml_unavailable Санкционная проверка временно недоступна Повторить позже
503 certificate_unavailable Справку сейчас сформировать нельзя Повторить позже

Частые случаи 409 conflict:

  • Заявитель с таким external_id в этом окружении уже существует (fields.external_id).
  • Сессия запрошена для заявителя не в статусе init — сначала сбросьте заявителя.
  • Проверка не в статусе ON_HOLD, устарела или её рассматривает другой проверяющий.
  • Решение RED ждёт подтверждения вторым проверяющим.
  • Справка запрошена для неокончательной проверки (не GREEN и не RED).
  • Запрос с тем же Idempotency-Key ещё выполняется.

Direct API использует ту же оболочку со своими кодами (например, invalid_file, image_too_large); они перечислены в его главе.

Hosted-страница возвращает 410 для истёкшей, использованной или неизвестной ссылки сессии, а kyc.js сообщает в onError link_invalid, session_expired или network. В этих случаях создайте новую сессию.

Лимиты запросов

Область Лимит
Все запросы к /api/v1 600 в минуту на API-ключ
Запросы с include= (данные документа, личность) 30 в минуту на API-ключ
Тест вебхука и повтор доставки 10 в минуту на API-ключ
GET /documents/catalog (без ключа) 60 в минуту на IP
Direct API 120 в минуту на IP и 60 в минуту на окружение ключа

В ответах есть X-RateLimit-Limit и X-RateLimit-Remaining. При превышении приходит 429 rate_limited с заголовком Retry-After в секундах.

429 plan_limit_reached — другое: это месячная квота боевого режима, а не поминутный лимит, и повторы не помогут, пока квота не освободится. Проверить её можно через GET /usage.

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

  • Повторяйте 429 rate_limited после Retry-After, а 500, 503 и сетевые ошибки — с экспоненциальной задержкой (например, 1, 2, 4, 8 секунд с небольшим случайным разбросом, несколько попыток).
  • Не повторяйте остальные 4xx без изменений — сначала исправьте запрос или состояние.
  • Передавайте Idempotency-Key в каждом POST, PATCH и DELETE и используйте тот же ключ при повторе той же операции. Повторный ответ содержит Idempotent-Replayed: true. Ответы 5xx не сохраняются, поэтому повтор после ошибки сервера выполнится заново. См. Аутентификация.
  • Если запрос на создание без Idempotency-Key прервался по таймауту, найдите объект перед повторным созданием — например, GET /applicants?external_id=….
  • Для решений предпочитайте вебхуки опросу. Доставка вебхуков повторяется примерно сутки — см. Вебхуки.

Версионирование

Версия — часть пути: /api/v1. В рамках v1 изменения только добавляются:

  • могут появляться новые эндпоинты, необязательные поля запроса, поля ответа, типы событий вебхуков, метки отказа, названия проверок и коды ошибок;
  • существующие поля, значения и коды не переименовываются и не удаляются.

Пишите клиент так, чтобы он игнорировал неизвестные поля и корректно обрабатывал неизвестные значения — например, неизвестную метку отказа считайте как ON_HOLD. Несовместимое изменение выйдет в новой версии (/api/v2).