Если из ста заказов вернулось девяносто семь, не запускайте весь файл ещё раз. Сначала составьте реестр из ста элементов: внутренний 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
- Остановить автоматический replay конкретного batch, не блокируя новые независимые возвраты.
- Зафиксировать локальные items и выгрузить refunds провайдера за тот же временной диапазон.
- Связать записи по provider ID, payment ID, сумме, валюте и operation metadata.
- Перевести найденные unknown в фактические состояния и выделить действительно неотправленные items.
- Повторить только их с исходным 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 или локальный переход состояния.