ДАРА
Кабинет Оставить заявку
Разделы документации

ДокументацияРуководства

Ошибки и лимиты

Формат ошибок API, HTTP-статусы и коды, ошибки полей, лимиты частоты и размеров, какие запросы повторять.

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

Ошибка приходит JSON-объектом с HTTP-статусом:

{"error": {"code": "validation_failed", "message": "Поля не прошли проверку",
  "details": [{"field": "published_at", "code": "invalid_datetime", "message": "укажите часовой пояс: Z или смещение, например 2026-09-14T12:00:00Z"}]}}
  • code — машинный код, по нему стоит ветвить обработку;
  • message — текст по-русски для логов и людей, может меняться;
  • details — список ошибок по полям {field, code, message}, есть не всегда.

Каждый ответ, в том числе с ошибкой, содержит X-Request-ID. Пишите его в логи и присылайте при обращении — по нему мы найдём запрос.

Коды

HTTP code Когда
400 invalid_request неверный JSON, неверные параметры строки запроса или пути
401 unauthorized нет ключа, ключ неверен или отозван
403 forbidden доступ приостановлен или проект в архиве
404 not_found объект не найден; у GET /users/profile — пользователь; у субтитров — ещё и медиа на этой позиции или транскрипт медиа
413 payload_too_large тело или пакет больше лимита; в переранжировании — больше 1000 id
422 validation_failed поля тела не прошли проверку; подробности — в details
429 rate_limited превышен лимит частоты; есть заголовок Retry-After
500 internal внутренняя ошибка; для разбора пришлите X-Request-ID
503 unavailable служба перегружена или на обслуживании; у выдачи — база данных недоступна и запасную выдачу собрать не из чего; у поиска — Retry-After: 1, когда поиск перегружен, и Retry-After: 2, когда сбой; у субтитров — очередь сборки файлов; есть Retry-After

Коды в details при 422, общие для разных методов:

Код Когда
required, invalid_type, invalid_value, too_long, unknown_field ошибки отдельных полей
too_many в массиве больше элементов, чем допускает поле: exclude выдачи — больше 500 id, items похожих — больше 20
invalid_user user — не объект, в нём неизвестное поле или идентификатор неверного формата: user_id длиннее 191 символа, anonymous_id не из печатных символов ASCII, fingerprint_uuid не UUID (при подключённом DARA Fingerprint, без подключения поле не проверяется), analytics_id не UUID; в field — путь, например user.fingerprint_uuid
pii_not_allowed в профиле переданы персональные данные — см. Данные о пользователях
unknown_filter фильтр выдачи или поиска по свойству, которое не отмечено в проекте фильтруемым, условие не подходит к типу свойства, null, пустой массив или больше 100 значений; в field — filters.<свойство>, см. Рекомендации
no_purchase_type заказ в проекте без типа события с флагом «покупка»

Все ошибки полей приходят одним ответом 422, до 20 строк details. Коды для объектов перечислены в разделе Объекты, причины отказа отдельных событий — в разделе События и заказы. Отклонённые события не делают весь запрос ошибкой: ответ 202 содержит список rejected.

GET /items/{id}/subtitles при успехе отдаёт не JSON, а файл субтитров; ошибки этого метода приходят в обычном формате — см. Результаты анализа. Ошибки загрузки файлов в кабинете устроены иначе: там коды строк и колонок собираются в отчёт, см. Импорт файлов.

Лимиты частоты

Лимиты защищают от атак и ошибок интеграции, тарифными ограничениями они не служат.

Что Лимит
выдача и поиск: /recommendations/*, /search 100 запросов в секунду на ключ, лимит общий
остальные методы: объекты, события, заказы, профили 20 запросов в секунду на ключ
все запросы к /api/ с одного IP 3000 в минуту с запасом на всплески, одновременно — не больше 50

Лимиты на ключ допускают кратковременный всплеск — до трёх секунд темпа: пачка запросов после паузы не получает 429. При превышении — 429 rate_limited с Retry-After в секундах. Если живая интеграция упирается в лимит, напишите нам — поднимем порог. Чтобы не упираться в лимит записи, передавайте данные пакетами: объекты — по 500, события — по 1000.

Лимиты размеров

Что Лимит
тело запроса 5 МБ
пакет объектов POST /items/batch 500 операций
события POST /events 1000 событий
профили POST /users/profile/batch 500 профилей
заказ POST /orders 200 строк
пакет заказов POST /orders/batch 500 заказов и 5000 строк
лента POST /recommendations/feed limit до 100, offset до 1000, exclude до 500 id
похожие POST /recommendations/similar limit до 50, items до 20 id
переранжирование POST /recommendations/rerank 1000 id
поиск POST /search query до 500 знаков, limit до 50, offset до 500
id объекта и user_id 191 символ Unicode
anonymous_id 191 печатный символ ASCII
id события и order_id 64 печатных символа ASCII
id в пути URL только A-Z a-z 0-9 . _ : -; другие — через пакетные методы

Месячные объёмы анализа

Если у проекта задан месячный объём анализа и он исчерпан, API не отвечает 429. Анализ новых объектов встаёт в ожидание — шаги в состоянии waiting, — а выдача, приём событий и запись данных продолжают работать. С новым месяцем или после повышения объёма задания продолжаются сами.

Повторы

Ответ Что делать
429 повторить после Retry-After
500, 503, обрыв соединения, таймаут повторить с растущей паузой: 1, 5, 30 секунд…
400, 401, 403, 404, 413, 422 не повторять без изменений: исправить запрос, ключ или данные

Повторы безопасны: PUT объекта идемпотентен, события не задваиваются благодаря id, заказы — благодаря order_id, запись профиля меняет только переданные поля.

Это повторы ваших запросов к ДАРА. Повторы вебхуков — запросов ДАРА на ваш адрес — идут по своему расписанию, см. Вебхуки.

Таймауты

Выдача рассчитана на ответ за доли секунды: если подбор не успевает, ДАРА отдаёт запасную выдачу с mode: fallback, а не ошибку. Ставьте таймаут на стороне сайта около 700 мс для выдачи (соединение — около 200 мс) и около десяти секунд для записи данных. На случай ошибки, таймаута и 503 держите собственный запасной вариант выдачи — например, хронологическую ленту — и не повторяйте запрос выдачи в том же показе страницы. Для поиска берите таймаут около полутора секунд: облачный вектор запроса добавляет к ответу время поставщика. Подробно — Рекомендации → Тайм-аут и запасная выдача и Поиск → Тайм-аут и ошибки.