Если из ста заказов вернулось девяносто семь, не запускайте весь файл ещё раз. Сначала составьте реестр из ста элементов: внутренний operation ID, payment ID, запрошенная сумма, idempotency key, provider refund ID и последнее подтверждённое состояние. Повторять можно только элементы без достоверного результата.

Общий HTTP-ответ или отметка «batch completed» здесь недостаточны. Платёжная операция живёт дольше одного запроса: она может остаться pending, завершиться после таймаута клиента или вернуть событие позднее. Пакет — это контейнер для наблюдения, а не одна атомарная финансовая транзакция.

У каждого заказа своя маленькая машина состояний

queued -> sending -> provider_pending -> succeeded
                    |                 -> failed
                    -> unknown -> reconcile -> provider_pending|succeeded|failed

idempotency_key = "refund:" + return_id + ":" + payment_id + ":v1"
batch_done = every(item.status in ["succeeded", "failed_manual"])

Unknown означает «клиент не знает результат», а не «провайдер ничего не сделал». Сетевой timeout после отправки запроса нельзя автоматически превращать в failed и создавать новую операцию с другим ключом. Сначала запросите refund по сохранённому provider ID, metadata или idempotency key; только отсутствие операции и документированно безопасный retry разрешают повтор.

Симптомы показывают, где пакет потерял элементы

Что видноВероятный разрывБезопасная проверка
Одинаковое число ошибок при каждом запускеВалидация данных или неподдерживаемый payment methodСохранить код и ответ по каждому item
Ошибки меняются местамиQuota, timeout или перегрузка зависимостиСопоставить время, latency и retry-after
Провайдер вернул деньги, локально unknownОтвет потерян после выполненияНайти refund по operation metadata
Успешные заказы вернулись повторноНовый ключ на каждый retryПроверить стабильность idempotency key
Весь batch повторяется из-за одного itemНет partial resultПодтверждать завершённые элементы отдельно

Stripe поддерживает idempotency keys для безопасного повтора POST: запрос с тем же ключом возвращает сохранённый результат первой начавшейся операции. Ключ должен описывать одну бизнес-операцию возврата, а не номер попытки и не весь batch. Новый ключ означает для API новую команду.

Повтор начинается со сверки, а не с POST

  1. Остановить автоматический replay конкретного batch, не блокируя новые независимые возвраты.
  2. Зафиксировать локальные items и выгрузить refunds провайдера за тот же временной диапазон.
  3. Связать записи по provider ID, payment ID, сумме, валюте и operation metadata.
  4. Перевести найденные unknown в фактические состояния и выделить действительно неотправленные items.
  5. Повторить только их с исходным idempotency key и контролируемым backoff.

Не используйте совпадение суммы и времени как единственное доказательство: у одного payment могут быть несколько частичных возвратов. Устойчивый ключ строится из return ID и payment ID, сохраняется до первого сетевого вызова и проходит через очередь, API client, журнал и webhook handler.

Partial batch не отдаёт успешные элементы на второй круг

Этот принцип одинаков для собственного worker и управляемой очереди. AWS Lambda для SQS прямо рекомендует partial batch response: обработчик сообщает идентификаторы неуспешных сообщений, чтобы уже завершённые не стали видимыми снова. Документация также предупреждает о доставке at least once, поэтому side effect обязан быть идемпотентным.

  • Ограничить concurrency по квоте платёжного API, а не по размеру входного CSV.
  • Разделить retryable ошибки, постоянную валидацию и ручное расследование.
  • Поставить предел попыток и quarantine для item, который стабильно падает.
  • Обрабатывать webhook повторно и вне порядка, сверяя текущее состояние объекта.
  • Показывать оператору итог: succeeded, pending, failed, unknown — без скрытого «прочее».

Приёмка специально обрывает связь

В sandbox отправьте небольшой пакет и оборвите ответ после того, как один refund уже создан. После восстановления worker должен найти существующую операцию, не сделать вторую и продолжить остальные items. Затем дайте одному элементу постоянную ошибку: batch не должен называться полностью успешным, но успешные элементы не должны возвращаться в очередь.

Для диагностики нужны batch ID, таблица item statuses, idempotency keys в хешированном или обезличенном виде, provider refund IDs, коды ошибок и времена попыток. API secret, номера карт и персональные данные не нужны. По такому журналу видно, что пропало: команда, ответ, webhook или локальный переход состояния.

Проверенные источники