Формат ошибки
{
"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).