ДокументацияРуководства
Ошибки и лимиты
Формат ошибок 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 держите собственный запасной вариант выдачи — например, хронологическую ленту — и не повторяйте запрос выдачи в том же показе страницы. Для поиска берите таймаут около полутора секунд: облачный вектор запроса добавляет к ответу время поставщика. Подробно — Рекомендации → Тайм-аут и запасная выдача и Поиск → Тайм-аут и ошибки.