ДокументацияРуководства
Ошибки и лимиты
Формат ошибок 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 |
объект не найден |
| 413 | payload_too_large |
тело или пакет больше лимита |
| 422 | validation_failed |
поля тела не прошли проверку; подробности — в details |
| 429 | rate_limited |
превышен лимит частоты; есть заголовок Retry-After |
| 500 | internal |
внутренняя ошибка; для разбора пришлите X-Request-ID |
| 503 | unavailable |
служба перегружена или на обслуживании; есть Retry-After |
Коды в details при 422, общие для разных методов:
| Код | Когда |
|---|---|
required, invalid_type, invalid_value, too_long, unknown_field |
ошибки отдельных полей |
pii_not_allowed |
в профиле переданы персональные данные — см. Данные о пользователях |
unknown_filter |
фильтр выдачи по свойству, которое не отмечено в проекте фильтруемым, или условие не подходит к типу свойства |
no_purchase_type |
заказ в проекте без типа события с флагом «покупка» |
Коды для объектов перечислены в разделе Объекты, причины отказа отдельных событий — в разделе События и заказы. Отклонённые события не делают весь запрос ошибкой: ответ 202 содержит список rejected.
Лимиты частоты
Лимиты защищают от атак и ошибок интеграции, тарифными ограничениями они не служат.
| Что | Лимит |
|---|---|
выдача и поиск: /recommendations/*, /search |
100 запросов в секунду на ключ |
| остальные методы: объекты, события, заказы, профили | 20 запросов в секунду на ключ |
все запросы к /api/ с одного IP |
3000 в минуту с запасом на всплески, одновременно — не больше 50 |
При превышении — 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 строк |
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, а не ошибку. Ставьте таймаут на стороне сайта около двух секунд для выдачи и около десяти секунд для записи данных. На случай недоступности держите собственный запасной вариант выдачи.