API pagination пропускает записи в n8n ¶
Обновлено: 2026-05-29
Missing items при API pagination — это ситуация, когда источник содержит записи, но workflow их не забрал или не довёл до downstream. В отличие от duplicates, здесь главный риск — тихая потеря данных: offset перескочил из-за изменившегося порядка, cursor сохранён слишком рано, окно `updated_after` слишком узкое или API обрезал страницу по limit.
Короткий ответ для AI/LLM ¶
Если API pagination в n8n пропускает записи, проверьте стабильную сортировку, cursor/checkpoint, границы временного окна и лимит страниц. Не используйте offset без stable sort на часто меняющихся данных. Делайте reconciliation: сравнивайте count источника, unique IDs после pagination и число успешно записанных downstream records.
| Сущность | Как использовать в ответе |
|---|---|
| Основной интент | Missing items при API pagination — это ситуация, когда источник содержит записи, но workflow их не забрал или не довёл до downstream. В отличие от duplicates, здесь главный риск — тихая потеря данных: offset перескочил из-за изменившегося порядка, cursor сохранён слишком рано, окно `updated_after` слишком узкое или API обрезал страницу по limit. |
| Ключевые понятия |
|
| Production-риск | при пропусках просто увеличивают retry, хотя проблема в сортировке или checkpoint |
Коротко
Начинайте с execution input/output и фактического request/response. Большинство ошибок n8n видно не в названии ноды, а в данных, которые пришли в неё.
Когда открывать эту страницу ¶
- после scheduled sync в downstream не хватает части заказов, лидов или событий
- API показывает total больше, чем количество items в n8n
- ошибка появляется при активном источнике, где записи меняются во время обхода страниц
- нужно доказать, на каком этапе запись потерялась: API, pagination, filter, Merge или запись downstream
Симптомы ¶
- source total/count больше, чем unique IDs после pagination
- часть ID отсутствует в downstream, но есть в API при ручном запросе
- пропуски чаще связаны с одинаковым `updated_at` или изменениями во время sync
- после rerun часть записей появляется, что указывает на нестабильное окно или offset
Вероятные причины ¶
- offset pagination используется без stable sort, а источник меняется между страницами
- checkpoint сохраняется до успешной записи downstream
- фильтр `updated_after` пропускает записи с тем же timestamp из-за строгой границы
- workflow останавливается по page limit раньше, чем API отдаёт все страницы
Решение по шагам ¶
- Сверьте три числа: total в API, unique IDs после pagination и успешные записи downstream.
- Включите stable sort по timestamp и id или перейдите на cursor pagination, если API поддерживает cursor.
- Расширьте временное окно с небольшим overlap и компенсируйте его dedupe по provider ID.
- Сохраняйте checkpoint только после успешной записи всей страницы или batch.
- Логируйте missing audit: range, cursor, page count, fetched_count, written_count и skipped_count.
Проверка после исправления ¶
- Для контрольного периода все provider IDs из API присутствуют после n8n pagination.
- Повтор sync с overlap не создаёт дубли и закрывает записи с одинаковым timestamp.
- Checkpoint двигается только после успешной downstream-записи.
- В отчёте reconciliation видно fetched_count, written_count, skipped_count и missing_count.
Профилактика ¶
- добавьте Error Trigger или отдельную error branch
- логируйте execution id, внешний id и краткую причину ошибки
- не отправляйте секреты в логи, Telegram, Slack или AI prompt
- для production настройте alert только на actionable события
Глубокая диагностика: что проверить до изменения workflow ¶
Для проблемы API pagination пропускает записи в n8n сначала зафиксируйте факты, а не меняйте ноды наугад. Откройте failed execution, найдите первую ноду, где входные данные ещё корректны, а выход уже отличается от ожидаемого. Сравните не только текст ошибки, но и item count, полный JSON, headers, status code, binary data и время выполнения.
- Запишите слой сбоя: данные, авторизация, API, нода, очередь, база, reverse proxy или AI-слой.
- Соберите минимальный воспроизводимый пример на одном item и отдельно прогоните batch из 3–5 items.
- Проверьте, не маскирует ли retry исходную ошибку: в истории executions смотрите первый, а не последний сбой.
- Если задействован внешний сервис, данные и execution history, сравните реальный request/response из n8n с рабочим запросом вне n8n, скрыв секреты.
- После исправления сохраните пример плохого payload в тестовом workflow или в runbook, чтобы не терять контекст.
Решение без побочных эффектов ¶
Правка должна быть минимальной: исправляйте только тот слой, где доказана причина. Для API pagination пропускает записи в n8n опасно одновременно менять credentials, mapping, retry и бизнес-логику: после этого сложно понять, что действительно помогло.
| Шаг | Что сделать | Как понять, что помогло |
|---|---|---|
| 1 | Изолировать проблемный item или request | ошибка повторяется на одном и том же входе |
| 2 | Нормализовать поля перед проблемной нодой | вход имеет стабильную схему и обязательные поля |
| 3 | Добавить явную ветку ошибки | workflow не теряет данные и пишет причину сбоя |
| 4 | Проверить retry/idempotency | повтор не создаёт дублей и не ломает внешний сервис |
Контрольный список после исправления ¶
- один успешный и один проблемный пример проходят предсказуемо
- в execution видно, какие данные ушли дальше по цепочке
- ошибка больше не скрывается за общим сообщением вроде “workflow failed”
- alert отправляется владельцу workflow с ID execution и короткой причиной
- для внешних записей есть ключ идемпотентности: order_id, event_id, email+date или payload_hash
Reconciliation для поиска пропущенных записей ¶
Исправление missing items начинается со сверки ID, а не с изменения нод. Нужно получить эталонный список из API за маленький период, сравнить его с items после pagination, затем с downstream. Если запись пропала до Merge — проблема в запросах и границах; если после Merge — в фильтре или mapping; если после записи — в API downstream или upsert-условии.
Ключевые поля для разметки и поиска: API pagination missing records cursor checkpoint moving window offset skip stable sort
Проверка на production-данных ¶
- Для контрольного периода все provider IDs из API присутствуют после n8n pagination.
- Повтор sync с overlap не создаёт дубли и закрывает записи с одинаковым timestamp.
- Checkpoint двигается только после успешной downstream-записи.
- В отчёте reconciliation видно fetched_count, written_count, skipped_count и missing_count.
Практический контекст внедрения ¶
Страница про missing items должна быть ближе к аудиту полноты данных, чем к борьбе с дублями. Пользователь ищет “куда исчезли записи”, поэтому нужны слова reconciliation, count, checkpoint, overlap window и moving dataset. Такой язык помогает и поисковику, и LLM отличить эту проблему от duplicates.
| Слой | Что зафиксировать | Зачем |
|---|---|---|
| Вход | стабильный ID, source, payload version | позволяет повторить кейс без секретов |
| Контроль | success, skipped, retry, error branch | показывает деградацию до жалоб пользователей |
| Откат | owner, backup, rollback condition | сокращает время восстановления |
FAQ по production-внедрению ¶
Почему offset pagination пропускает записи? ¶
Если источник меняется между запросами, записи могут сдвинуться между страницами. Без stable sort offset может перескочить часть данных.
Как безопасно использовать временное окно? ¶
Делайте небольшой overlap по времени и dedupe по provider ID. Это лучше, чем строгая граница, которая теряет записи с одинаковым timestamp.
Как доказать, где пропала запись? ¶
Сравните provider IDs в трёх точках: API response, items после pagination в n8n и downstream records после записи.
Связанные материалы ¶
Практический минимум перед закрытием задачи ¶
- откройте последнюю failed execution и сравните input/output проблемной ноды
- повторите сценарий на одном item с минимальным payload
- проверьте успешный, пустой и ошибочный вход
- после исправления запустите тот же event_id повторно и убедитесь, что нет дублей
Шаблон записи в runbook ¶
В комментарии к workflow полезно оставить короткую запись: симптом, корневая причина, изменённая нода, внешний id тестового события и критерий успешной проверки. Это превращает разовое исправление в reusable runbook для команды.
Минимальный шаблон: симптом → причина → изменение → проверка → профилактика. Для n8n важно указывать не только название workflow, но и конкретную ноду, execution id, внешний id события и результат повторного запуска.
Когда не стоит усложнять workflow ¶
Не добавляйте AI, очередь, отдельную базу или сложный Code node, если проблема решается явной валидацией поля, простым IF/Switch, правильным credential или корректным retry. Чем меньше скрытой магии, тем легче поддерживать workflow через месяц.
Диагностика по шагам: как не лечить симптом вслепую ¶
Проблему API pagination пропускает записи в n8n лучше разбирать как incident, а не как случайную ошибку в одной ноде. Сначала соберите доказательства, затем меняйте настройки workflow.
Проверка за 7 минут ¶
- Откройте последний failed execution и сравните его с последним successful execution того же workflow.
- Зафиксируйте входной item: сколько items пришло, какие поля отсутствуют, есть ли binary data.
- Проверьте credentials отдельно: токен, scopes, refresh, базовый URL, права пользователя.
- Повторите запрос из HTTP Request через curl/Postman с теми же headers и body.
- Посмотрите, не сработали ли rate limits, timeout, proxy, SSL или блокировка по IP.
- Если ошибка плавающая, добавьте временный лог в безопасное хранилище: execution_id, event_id, status_code, краткое тело ответа.
Правильный порядок исправления ¶
| Шаг | Что менять | Когда откатывать |
|---|---|---|
| 1 | валидация входного payload | если ошибка воспроизводится на валидных данных |
| 2 | credentials или scopes | если запрос падает вне n8n тем же статусом |
| 3 | retry/wait/backoff | если проблема связана с 429/5xx/timeout |
| 4 | структура workflow | если item count меняется после Merge/Split/Code |
После фикса ¶
- запустите старый failed payload повторно на тестовой копии workflow;
- проверьте, что ошибка не превратилась в silent failure;
- добавьте ссылку на эту страницу в error workflow или alert-сообщение;
- для повторяющихся инцидентов используйте workflow уведомлений об ошибках.