Ошибки и повторы

Ingest отвечает двумя способами:

• 200 с IngestResult — батч обработан. Часть событий может быть отклонена (rejected) или принята с поправкой (warnings). Это не ошибка батча.
• 4xx или 5xx с конвертом error — батч не обработан целиком.

Клиент ветвится только по HTTP-статусу и полю code, а не по тексту message.

Что делать клиентуСкопировать ссылку на раздел

Повтор того же батча безопасен: дубликаты отсекаются по insert_id, а метрики считаются по уникальным идентификаторам. При каждом повторе выставляйте новый sent_at. Готовые повторы — в рецептах curl (скрипт на bash) и Go.

Частичный успехСкопировать ссылку на раздел

Батч из двух событий, где у второго user_id похож на телефон:

NOW=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
curl -sS https://i.analytics.example.com/v1/events \
  -H "Content-Type: application/json" \
  -H "X-App-Key: $AM_PK" \
  --data-binary @- <<JSON
{
  "sent_at": "$NOW",
  "context": { "platform": "server", "environment": "development", "ip": "none" },
  "events": [
    {
      "insert_id": "$(uuidgen | tr A-Z a-z)",
      "name": "session_start",
      "timestamp": "$NOW",
      "install_id": "$(uuidgen | tr A-Z a-z)",
      "session_id": "$(uuidgen | tr A-Z a-z)"
    },
    {
      "insert_id": "$(uuidgen | tr A-Z a-z)",
      "name": "session_start",
      "timestamp": "$NOW",
      "install_id": "$(uuidgen | tr A-Z a-z)",
      "session_id": "$(uuidgen | tr A-Z a-z)",
      "user_id": "+79161234567"
    }
  ]
}
JSON

Первое событие принято, второе отклонено:

{
  "accepted": 1,
  "rejected": [
    {
      "index": 1,
      "insert_id": "0199d6c1-0000-7000-8000-000000000005",
      "code": "user_id_looks_like_pii",
      "field": "events[1].user_id",
      "message": "user_id похож на email или телефон. Передавайте непрозрачный ID.",
      "retryable": false
    }
  ],
  "warnings": [],
  "server_time": "2026-10-14T09:15:02.318Z"
}

index — позиция события в массиве events, field — путь к полю с ошибкой.

Отклонённые событияСкопировать ссылку на раздел

Отклонённые события видны на вкладке «Интеграция» с кодом и версией приложения 7 дней, затем удаляются.

ПредупрежденияСкопировать ссылку на раздел

Событие с предупреждением принято и учтено в accepted.

platform_missing приходит по одному на событие. Чтобы его не было, передавайте context.platform или отправляйте события ключом нужной платформы — см. Платформа события.

Ошибки батчаСкопировать ссылку на раздел

{
  "error": {
    "code": "invalid_batch",
    "message": "events: от 1 до 500 событий.",
    "request_id": "01JA8Z3K7Q2M9V4T6R1X5N8C0C",
    "details": { "field": "events", "issue": "max_items" }
  }
}

request_id совпадает с заголовком ответа X-Request-Id. По нему запрос находится в логах сервера.

Ответ 200 приходит только после того, как ClickHouse подтвердил запись. Если подтверждения нет за 5 секунд, весь батч получает 503, и клиент повторяет его целиком.