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

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

Ошибка запроса целиком приходит с HTTP-кодом 4xx или 5xx и телом:

{"error": {"code": "validation_failed", "message": "Поле date_from обязательно"}}

• code — машинный код из таблицы ниже. Проверяйте в коде именно его.
• message — пояснение для человека; текст может меняться.
• details — необязательный объект с подробностями, например о полях, которые не прошли проверку.

Каждый ответ содержит заголовок X-Request-ID — сохраняйте его в логах.

Ответы веб-сервера#

Часть ответов формирует не сервис, а веб-сервер перед ним:

• 403 на http://. API работает только по HTTPS: запрос по http:// не перенаправляется, а сразу получает 403 с кодом forbidden, без заголовка X-Request-ID. Ключ в таком запросе уже ушёл по сети открытым — отзовите его и создайте новый.
• 413 — тело больше 1 МБ, и 429 — превышен лимит запросов с одного IP, в том же формате JSON. У 429 по IP заголовок Retry-After: 2.
• 503 с Retry-After: 10 — служба API не отвечает веб-серверу, например перезапускается. Сам сервис отвечает 503 с Retry-After: 5, когда не может прочитать данные.
• 5xx не в JSON. Если сбой случился на входе, до службы API, — например, при перезапуске веб-сервера — ответ 5xx может прийти страницей HTML без заголовка X-Request-ID. Решайте по HTTP-коду, а не по телу: такой ответ повторяйте, как 500 и 503.

Сайт запроса#

Ключ аккаунта (aa_…) работает со всеми сайтами аккаунта, поэтому каждый запрос называет сайт заголовком X-Dara-Site — подробности и примеры в разделе API.

GET /meta, GET /network и GET /categories отвечают одинаково для всех сайтов, поэтому им заголовок не нужен.

Проверка отчёта#

POST /reports с неверным определением отвечает 422 с кодом validation_failed. В details — поле и код причины:

{"error": {"code": "validation_failed", "message": "Неизвестная метрика", "details": [{"field": "metrics[1]", "code": "unknown_metric"}]}}

Если отчёт не уложился во время даже по выборке, ответ — 503 с кодом unavailable: сократите период.

Ошибки отдельных записей#

Методы пачек отвечают 202 Accepted, даже если часть записей не принята. Непринятые записи перечислены в ответе.

index — номер записи в пачке, с нуля. duplicates в ответе POST /conversions и POST /orders — записи, которые уже были учтены: это не ошибка.

POST /ad-costs — пачка «всё или ничего»: ответ 200, а при ошибке хотя бы одной строки — 422 с кодом validation_failed, и не пишется ни одна строка. В details — ошибки всех строк сразу, например costs[3].amount. Свои коды метода: no_rate — нет курса ЦБ для валюты строки на её дату (укажите сумму в валюте сайта); duplicate — та же строка (дата и три метки) дважды в пачке; too_many у поля costs — больше 1000 строк в пачке или больше 200 000 строк расходов у сайта.

Ошибка формы хотя бы одного элемента POST /visitors/attributes или записи POST /users — неверный тип, длина, UUID, нет идентификатора — отклоняет весь запрос ответом 422 с кодом validation_failed, а в details — поле с номером элемента, например visitors[3].visitor_id или users[3].email. POST /users отвечает 503 с кодом unavailable, если приём временно недоступен: пачка не сохранена, её нужно отправить ещё раз.

Повторы#

• Повторяйте при сетевой ошибке, 429, 500 и 503 — с растущей паузой, а при Retry-After — не раньше указанного времени.
• Не повторяйте без исправления остальные ответы 4xx: результат будет тем же.
• Пачки конверсий и заказов можно отправлять повторно без риска задвоить данные: конверсии узнаются по id, заказы — по transaction_id.
• Пачку POST /users тоже можно повторить: повтор той же пачки второй раз не записывается — ни поля, ни interests. Ответ приходит тот же, вместе с заголовком Idempotent-Replayed: true; пачка узнаётся по содержимому 15 минут, а с вашим заголовком Idempotency-Key — сутки. Тот же Idempotency-Key с другой пачкой — ответ 422 с полем Idempotency-Key в details: имя уже занято, возьмите новое (Данные о посетителях).

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

Лимит частоты считается на ключ, а не на сайт: ключ аккаунта с сотней сайтов не получает сотню бюджетов, а сайт из заголовка X-Dara-Site на лимит не влияет. Ключу аккаунта бюджеты вчетверо шире, потому что он ходит за все сайты сразу.

Сверх лимита, в том числе при третьем одновременном отчёте ключа сайта и пятом одновременном отчёте аккаунта, сразу приходит ответ 429 с кодом rate_limited и заголовком Retry-After. Ответ /visitors/* из кеша тоже расходует лимит, и отказы — тоже: неверный сайт в заголовке и ключ сайта там, где нужен ключ аккаунта, расходуют лимит чтения так же, как чтение.

• Retry-After лимита на ключ — секунды до конца окна лимита: у лимитов в секунду и у занятых слотов отчётов — 1, у лимита отчётов в минуту — до 60.
• Retry-After лимита запросов с одного IP — 2.

Размеры пачек#

Квоты сайта#

Сервис бесплатный, нагрузку ограничивают квоты. Администратор ДАРА может изменить квоты для сайта или пользователя.

Роботы учитываются в квоте хитов: они тоже нагружают сервер. Как считаются отчёты сверх квоты — в разделе Отчёты и метрики.

Пределы тега#

Посетитель, который превысил лимиты запросов, получает отметку робота с причиной «Частота», а лишние события отбрасываются.

Лишние элементы children и interests и строки длиннее предела тег обрезает, а поля dara('user') с неверным значением не отправляет — остальные поля команды уходят. В POST /users пределы строк шире — phone до 64 символов, city до 200 — а превышение даёт 422.

Пределы отчётов#