Идемпотентность и ретраи через прокси: как повтор запроса не создаёт дубль заказа
Содержание статьи
- Введение: одна кнопка, два заказа и туннель, в котором теряются ответы
- Основы: что такое идемпотентность и почему повтор запроса вообще опасен
- Глубокое погружение: серверный контракт и анатомия безопасного повтора
- Метод 1: генерация и передача идемпотентного ключа на стороне клиента
- Метод 2: серверная реализация хранилища ключей
- Метод 3: протокол повторов через прокси, который не ломает идемпотентность
- Метод 4: когда сервер не поддерживает идемпотентные ключи
- Типичные ошибки: как команды сами создают дубли
- Инструменты и ресурсы для реализации
- Кейсы и результаты
- Faq: сложные вопросы об идемпотентности и повторах
- Заключение: контракт вместо надежды
Введение: одна кнопка, два заказа и туннель, в котором теряются ответы
Представьте интеграцию, которая работает годами. Ваш сервис отправляет заказы во внешнюю систему, поток идёт через пул мобильных прокси, чтобы распределять запросы по регионам и не упираться в лимиты одного адреса. Всё стабильно. И вдруг бухгалтерия приносит отчёт: за месяц у партнёра появилось сорок семь заказов-близнецов. Одинаковые товары, одинаковые суммы, разница во времени создания три-четыре секунды. Никто ничего не менял. Что произошло?
Произошло самое обычное: соединение через прокси оборвалось на обратном пути. Сервер получил запрос, создал заказ, отправил ответ, но ответ не добрался до клиента. Клиент честно решил, что запрос не удался, и повторил его. Второй запрос тоже выполнился. Так рождается дубль, и никакая политика повторов сама по себе от него не защищает.
Здесь важно сразу провести границу. О том, как правильно повторять запросы после ошибки 429, сколько ждать между попытками и как строить экспоненциальную задержку, мы писали отдельно: это тема политики ретраев. Сегодня разговор другой. Мы говорим о контракте между клиентом и сервером, который делает повтор безопасным или опасным независимо от того, как именно вы его выполняете. Этот контракт называется идемпотентностью, а его главный инструмент — идемпотентный ключ.
Почему тема особенно остра именно при работе через прокси? Потому что прокси добавляет в цепочку ещё один участок, где ответ может потеряться. Мобильные прокси вдобавок меняют внешний IP при ротации, и сервер вполне может увидеть второй запрос с другого адреса. Если ваша защита от дублей опирается на сессию, IP или временное окно, она рассыпается. Если она опирается на идемпотентный ключ, ей всё равно, откуда пришёл повтор.
Из этого руководства вы узнаете, как устроена идемпотентность на уровне протокола и бизнес-логики, как генерировать и хранить ключи, как спроектировать серверное хранилище, которое выдерживает конкурентные повторы, что делать, если внешний API ключей не поддерживает, и на каких ошибках спотыкаются даже опытные команды. Мы разберём кейсы с цифрами, соберём чек-листы и ответим на неудобные вопросы. Материал рассчитан на разработчиков интеграций, архитекторов и технических лидов, которые работают с заказами, платежами и любыми операциями, где «дважды» означает «плохо».
Основы: что такое идемпотентность и почему повтор запроса вообще опасен
Определение простыми словами
Операция называется идемпотентной, если её многократное выполнение даёт тот же результат, что и однократное. Нажать кнопку вызова лифта десять раз — идемпотентно: лифт приедет один. Положить в корзину ещё одну единицу товара — не идемпотентно: каждое нажатие меняет состояние. Перевести деньги — точно не идемпотентно, если только система специально не спроектирована так, чтобы повтор перевода с тем же идентификатором ничего не делал.
В HTTP есть методы, которые по спецификации считаются идемпотентными: GET, PUT, DELETE, HEAD. Есть метод POST, который по умолчанию идемпотентным не считается. Именно POST чаще всего используют для создания заказов, оплат, отправки сообщений. То есть самая рискованная операция живёт в самом неидемпотентном методе. Совпадение? Скорее историческая закономерность, с которой приходится работать.
Три исхода любого запроса
Когда клиент отправляет запрос и не получает ответ, он оказывается в состоянии неопределённости. Возможны ровно три сценария:
- Запрос не дошёл до сервера. Повторять безопасно: ничего не произошло.
- Запрос дошёл, сервер выполнил операцию, ответ потерялся. Повторять опасно: операция выполнится второй раз.
- Запрос дошёл, сервер начал выполнение и ещё не закончил. Повторять опасно вдвойне: две операции будут выполняться параллельно.
Ключевая беда в том, что клиент не может различить эти сценарии. Таймаут выглядит одинаково во всех трёх случаях. Разорванное соединение — тоже. Отсюда следует фундаментальный принцип распределённых систем: надёжная доставка возможна только как «хотя бы один раз» (at-least-once). Гарантию «ровно один раз» (exactly-once) на транспортном уровне получить нельзя; её можно только эмулировать на уровне приложения, делая повторы безвредными. Идемпотентность и есть этот способ эмуляции.
Как прокси удлиняет цепочку неопределённости
Без прокси между клиентом и сервером один сетевой участок. С прокси их два: клиент — прокси и прокси — сервер. Ответ может потеряться на любом из них. Причём если он потерялся на первом участке, то прокси уже получил ответ, сервер уже завершил операцию, а клиент об этом не узнает никогда.
Мобильные прокси добавляют специфику. У них ротация IP по расписанию или по запросу, переключение между базовыми станциями, естественные колебания качества радиоканала. Каждое из этих событий способно разорвать TCP-соединение в произвольный момент. Причём чаще всего разрыв происходит не во время передачи тела запроса (оно маленькое и улетает быстро), а во время ожидания ответа, когда соединение просто держится открытым. Именно в этот момент сервер обрабатывает ваш заказ. Именно в этот момент разрыв даёт максимальный шанс на дубль.
Что такое идемпотентный ключ
Идемпотентный ключ (Idempotency-Key) — это уникальный идентификатор бизнес-операции, который клиент генерирует один раз и передаёт с каждой попыткой выполнить эту операцию. Сервер запоминает ключ и результат. При повторном запросе с тем же ключом сервер не выполняет операцию заново, а возвращает сохранённый результат. Клиент может повторять сколько угодно: заказ будет создан один раз.
Обратите внимание на формулировку: ключ идентифицирует операцию, а не HTTP-запрос. Это различие станет центральным дальше, когда мы будем разбирать ошибки реализации.
Глубокое погружение: серверный контракт и анатомия безопасного повтора
Контракт как договор о поведении
Идемпотентность — это не заголовок и не библиотека. Это договор, в котором сервер обещает клиенту конкретное поведение при повторах, а клиент обещает соблюдать правила формирования ключей. Хороший контракт отвечает на следующие вопросы:
- Какая сущность является единицей идемпотентности: заказ, платёж, строка заказа, батч?
- Как клиент передаёт ключ: заголовок, поле тела, часть URL?
- Что происходит, если ключ совпал, а тело запроса другое?
- Что происходит, если первый запрос ещё выполняется, а пришёл второй с тем же ключом?
- Как долго сервер помнит ключ?
- Что вернётся при повторе: тот же самый ответ байт в байт, или актуальное состояние сущности?
- Как повтор отличается от нового запроса в логах и метриках?
Если хотя бы на один из этих вопросов нет ответа в документации API, контракт неполный, и в неопределённых ситуациях поведение будет зависеть от реализации, версии и фазы луны.
Три состояния ключа
На сервере у каждого ключа есть жизненный цикл из трёх состояний. Понимание этого цикла объясняет девяносто процентов проблем с дублями.
- Отсутствует. Ключ впервые виден. Сервер должен атомарно зарезервировать его и начать обработку.
- В процессе (in-progress). Первый запрос обрабатывается. Второй запрос с тем же ключом не должен запускать вторую обработку. Варианты: вернуть 409 Conflict с указанием подождать, заблокироваться до завершения первого и вернуть его результат, вернуть 202 Accepted с ссылкой на статус.
- Завершён. Результат сохранён. Повтор возвращает сохранённый результат без побочных эффектов.
Самая частая архитектурная ошибка — пропуск среднего состояния. Разработчик проверяет «есть ли ключ в базе», не находит, начинает обработку, и параллельный повтор в этот же момент делает то же самое. Два потока, две проверки, два заказа. Проверка и резервирование должны быть одной атомарной операцией: вставка с уникальным индексом, условная запись в Redis, транзакция с блокировкой.
Отпечаток запроса
Ключ идентифицирует операцию, но операцию с каким содержимым? Если клиент из-за бага отправил ключ K с суммой 1000 рублей, а затем повторил с тем же ключом и суммой 10000, что должен сделать сервер? Вернуть результат первой операции молча — опасно: клиент будет думать, что оплатил 10000. Выполнить вторую — нарушить идемпотентность.
Правильный ответ: сервер хранит отпечаток (fingerprint) запроса — хеш нормализованного тела и значимых заголовков. При повторе с тем же ключом, но другим отпечатком возвращается ошибка 422 Unprocessable Content или 400 с явным кодом вида idempotency_key_reused_with_different_payload. Это защищает от логических ошибок клиента и от подделки повторов.
Хранение ответа: снимок или актуальное состояние
Существует два подхода к тому, что возвращать при повторе. Снимок — сервер сохраняет статус, заголовки и тело оригинального ответа и возвращает их без изменений. Это строго идемпотентно и предсказуемо. Актуальное состояние — сервер по ключу находит созданную сущность и возвращает её текущее представление. Это удобнее, если между попытками заказ успел перейти в другой статус, но менее предсказуемо.
В платёжных системах доминирует снимок: клиент должен получить именно тот ответ, который был у первой попытки. В системах управления заказами часто применяют гибрид: снимок для кодов ошибок, актуальное состояние для успеха. Главное, чтобы выбор был зафиксирован в контракте.
Что меняет прокси на уровне контракта
Технически прокси не участвует в контракте идемпотентности: он прозрачен для заголовков и тела. Но он меняет вероятности. Через прямое соединение потеря ответа при успешном выполнении — редкость, доля процента от процента. Через цепочку с мобильным прокси и ротацией это событие становится регулярным. Мы наблюдали интеграции, где при пятиминутной ротации IP порядка 0,3–0,8% запросов завершались обрывом соединения на этапе ожидания ответа. При десяти тысячах заказов в сутки это тридцать-восемьдесят потенциальных дублей ежедневно. Без идемпотентного ключа каждый из них превращается в реальный дубль.
Есть и вторая тонкость. Многие серверы включают в антифрод-логику проверку «повторный запрос с другого IP». При ротации мобильного прокси повтор почти всегда придёт с нового адреса. Если сервер трактует это как подозрительную активность и отклоняет повтор без обращения к хранилищу ключей, клиент не получит сохранённый результат и останется в неопределённости. Хороший контракт проверяет ключ до любых эвристик, привязанных к сети.
Метод 1: генерация и передача идемпотентного ключа на стороне клиента
Где рождается ключ
Главное правило: ключ генерируется один раз на бизнес-операцию, до первой попытки отправки, и сохраняется вместе с намерением выполнить операцию. Если ключ создаётся внутри HTTP-клиента при каждом вызове, ретрай получит новый ключ, и вся защита обнулится. Это настолько частая ошибка, что мы вынесем её отдельно в раздел про антипаттерны, но повторим здесь: ключ живёт на уровне сервиса заказов, а не на уровне транспорта.
Практическая последовательность выглядит так:
- Пользователь или внутренний процесс инициирует создание заказа.
- Сервис создаёт локальную запись «намерение заказа» со статусом pending и генерирует ключ.
- Ключ и полезная нагрузка сохраняются в локальной базе в одной транзакции.
- Только после фиксации транзакции запускается отправка во внешний API через прокси.
- Все повторы читают ключ из локальной записи, а не генерируют новый.
- После получения ответа локальная запись обновляется результатом и внешним идентификатором заказа.
Такой порядок гарантирует, что даже перезапуск вашего сервиса посреди ретраев не приведёт к смене ключа: он лежит в базе.
Формат ключа
Ключ должен быть уникальным глобально и непредсказуемым для третьих лиц. Рабочие варианты:
- UUID версии 4 — классика, 122 бита случайности, подходит везде.
- UUID версии 7 или ULID — содержат временную метку в старших битах, что делает их удобными для сортировки и индексирования в базе сервера. В 2026 году это уже стандартный выбор для новых систем.
- Детерминированный ключ из естественного идентификатора — например, хеш от идентификатора корзины, идентификатора пользователя и версии корзины. Полезен, когда клиент сам может потерять состояние и сгенерировать ключ повторно из тех же данных.
Чего избегать: последовательных чисел (легко угадать чужой ключ и получить чужой ответ), коротких строк, ключей, зависящих только от времени с низкой точностью.
Способ передачи
Стандарт де-факто — заголовок Idempotency-Key. Черновик спецификации IETF закрепляет именно это имя, и большинство современных API его придерживаются. Пример вызова через прокси:
curl -x http://user:pass@proxy.example:8080 -H "Idempotency-Key: 018f3a2c-7b1e-7c3d-9a4e-1f2b3c4d5e6f" -H "Content-Type: application/json" -d '{"cart_id":"c-9921","amount":149000}' https://api.partner.example/v1/orders
Некоторые API принимают ключ в теле запроса (поле client_reference_id, external_id, request_id). Это тоже рабочий вариант, но с одним нюансом: если сервер использует поле тела как ключ, оно обязательно должно участвовать в уникальном индексе, иначе это просто метка, а не защита.
Область действия ключа
Ключ должен быть уникален в пределах одного клиента-аккаунта и одного эндпоинта. Хороший сервер составляет внутренний ключ хранения как комбинацию идентификатора аккаунта, метода, пути и переданного ключа. Это защищает от коллизий между разными клиентами и от случайного переиспользования ключа для другой операции.
Чек-лист клиентской стороны
- Ключ генерируется до первой попытки и хранится в базе вместе с намерением.
- Все ретраи используют тот же ключ.
- Тело запроса при ретрае байт в байт совпадает с первой попыткой.
- Клиент умеет обрабатывать 409 (операция в процессе) как сигнал подождать и повторить, а не как ошибку.
- Клиент умеет обрабатывать 422 с кодом несовпадения отпечатка как логическую ошибку, требующую вмешательства.
- Клиент логирует ключ во всех записях, связанных с операцией, чтобы дубли можно было расследовать.
- Клиент не сбрасывает ключ при смене прокси, ротации IP или переключении на резервный пул.
Метод 2: серверная реализация хранилища ключей
Если вы владеете сервером, к которому обращаются через прокси ваши клиенты или партнёры, этот раздел о вас. Если вы только клиент, он поможет оценить качество чужой реализации по документации и поведению.
Схема хранения
Минимальная таблица или структура для ключей содержит следующие поля:
- scope_key — составной ключ: аккаунт, метод, путь, переданный Idempotency-Key. Уникальный индекс.
- fingerprint — хеш нормализованного тела запроса.
- state — одно из значений: in_progress, completed, failed.
- response_status, response_headers, response_body — снимок ответа, заполняется при завершении.
- resource_id — идентификатор созданной сущности, если применимо.
- locked_at, completed_at, expires_at — временные метки для обработки зависших операций и очистки.
Атомарное резервирование
Сердце реализации — операция, которая одним действием либо создаёт запись в состоянии in_progress, либо сообщает, что запись уже есть. В реляционной базе это вставка с обработкой конфликта по уникальному индексу. В Redis — команда SET с флагами NX и EX, которая записывает значение только при отсутствии ключа и сразу задаёт время жизни. Никаких «сначала SELECT, потом INSERT»: между ними пролезет параллельный повтор.
Псевдокод на уровне логики:
- Вычислить scope_key и fingerprint.
- Попытаться вставить запись со state = in_progress. Если вставка успешна, перейти к выполнению операции.
- Если конфликт: прочитать существующую запись.
- Если fingerprint не совпадает — вернуть 422 с кодом несовпадения.
- Если state = in_progress — вернуть 409 с заголовком Retry-After или ждать завершения (в пределах разумного таймаута).
- Если state = completed — вернуть сохранённый снимок ответа с заголовком, помечающим повтор, например
Idempotent-Replayed: true.
Выполнение и фиксация результата
Здесь кроется вторая ловушка. Операция выполнилась, заказ создан, но процесс упал до записи результата в хранилище ключей. Запись остаётся в состоянии in_progress навсегда. Повтор получает 409, потом ещё 409, и так до бесконечности.
Есть три подхода к решению:
- Единая транзакция. Создание заказа и обновление записи ключа выполняются в одной транзакции базы данных. Самый надёжный вариант, если заказ и ключи живут в одной базе.
- Ключ как часть сущности. Идемпотентный ключ хранится прямо в таблице заказов с уникальным индексом. Тогда сам заказ и есть запись о ключе; отдельная таблица не нужна. Просто и надёжно для случаев с одной сущностью на операцию.
- Восстановление зависших. Фоновый процесс находит записи in_progress старше порога (например, 60 секунд), проверяет, была ли операция фактически выполнена (по resource_id или поиску сущности), и либо доводит фиксацию, либо переводит запись в failed, разрешая повтор.
Обработка ошибок первой попытки
Что сохранять, если первая попытка завершилась ошибкой? Зависит от типа ошибки. Ошибки валидации (400, 422) детерминированы: повтор с тем же телом даст тот же результат, их можно кэшировать. Ошибки инфраструктуры (500, 503, таймаут базы) не детерминированы: если их закэшировать, клиент никогда не сможет успешно выполнить операцию. Правильное поведение: при инфраструктурной ошибке освободить ключ (удалить запись или перевести в failed с возможностью перезахвата), чтобы следующий повтор попробовал снова.
Время жизни ключа
Ключи нельзя хранить вечно: таблица разрастётся. Но и слишком короткий срок опасен: если клиент повторяет через полчаса после сетевой аварии, ключ должен быть жив. Практика крупных платёжных провайдеров сходится на 24 часах как минимуме. Для заказов в электронной коммерции разумны 24–72 часа. Для операций, которые клиент может повторять после длительных сбоев (например, синхронизация каталогов раз в сутки), срок должен превышать интервал синхронизации хотя бы вдвое.
Наблюдаемость
Каждый повтор должен оставлять след. Метрики, которые стоит собирать: количество повторов с попаданием в completed (безвредные повторы), количество 409 (конкурентные повторы), количество 422 (несовпадение отпечатка — почти всегда баг клиента), возраст самой старой записи in_progress (индикатор зависших операций). Соотношение повторов и уникальных операций — прямая мера качества сети между клиентом и сервером. Если оно резко растёт, где-то ухудшилось качество прокси-канала или изменилась ротация.
Чек-лист серверной стороны
- Резервирование ключа атомарно.
- Есть отдельное состояние in_progress и понятный ответ на конкурентный повтор.
- Хранится отпечаток тела, несовпадение отклоняется явной ошибкой.
- Фиксация результата транзакционна или есть механизм восстановления зависших записей.
- Инфраструктурные ошибки не кэшируются, детерминированные — кэшируются.
- TTL не меньше 24 часов и задокументирован.
- Повтор помечается заголовком и виден в метриках.
- Проверка ключа происходит раньше сетевых эвристик антифрода.
Метод 3: протокол повторов через прокси, который не ломает идемпотентность
Политика ретраев — тема соседней статьи, но есть узкий пласт, где политика повторов и идемпотентность пересекаются: какие именно сигналы от прокси-цепочки означают, что повтор нужен, и как повтор не должен разрушать контракт. Разберём его.
Различайте отказ прокси и отказ апстрима
При работе через прокси клиент получает ошибки трёх происхождений, и реагировать на них нужно по-разному:
- Ошибки соединения с прокси. Не удалось подключиться к прокси, прокси вернул 407 (требуется аутентификация), прокси закрыл соединение до отправки запроса. Запрос гарантированно не дошёл до сервера. Повтор безопасен даже без ключа, но с ключом — всё равно лучше.
- Ошибки прокси при обращении к апстриму. Прокси вернул 502 Bad Gateway или 504 Gateway Timeout. Здесь неопределённость максимальна: 502 обычно означает, что апстрим не ответил корректно, но мог выполнить операцию; 504 означает, что прокси устал ждать, а сервер, возможно, всё ещё обрабатывает. Повтор только с ключом.
- Ответы апстрима, прошедшие через прокси. 500, 503, 429 от целевого сервера. Их семантика определяется контрактом целевого API. Повтор с ключом по правилам политики повторов.
Отдельного внимания заслуживает разрыв соединения во время чтения ответа. Заголовки уже пришли, тело оборвалось. Это самый коварный случай: статус 201 Created вы, возможно, увидели, но идентификатор заказа из тела не получили. Повтор с ключом вернёт полный снимок ответа. Без ключа вы получите второй заказ и при этом так и не узнаете идентификатор первого.
Ротация IP как событие, а не как фон
Если ваш пул мобильных прокси ротирует адреса по расписанию, синхронизируйте отправку критичных операций с окнами стабильности. Простой приём: узнавать у API прокси-сервиса время до следующей ротации и не начинать создание заказа, если до ротации меньше, чем ваш таймаут ожидания ответа. Это не заменяет идемпотентность, но снижает число повторов, а значит, нагрузку на хранилище ключей и на антифрод партнёра.
Если ротация происходит по запросу, не вызывайте смену IP между попытками одной операции без необходимости. Некоторые команды делают так «чтобы обойти залипание», но сервер, увидев тот же ключ с нового адреса, может включить дополнительную проверку. Ключ спасёт от дубля, но повтор может замедлиться.
Таймауты: две границы вместо одной
При прямом соединении обычно задают один таймаут на ответ. Через прокси нужны как минимум два: таймаут установления соединения с прокси (короткий, единицы секунд) и таймаут ожидания ответа от апстрима (длиннее, с учётом времени обработки заказа). Если объединить их в один, короткий таймаут будет постоянно срабатывать при медленной обработке, порождая лишние повторы, а длинный — заставит ждать недоступный прокси лишние секунды.
Важно: таймаут ожидания ответа не должен быть меньше реального времени создания заказа на сервере. Иначе вы систематически будете обрывать соединение ровно в момент обработки, и каждая операция будет превращаться в пару «оборванная попытка плюс повтор». Ключ убережёт от дублей, но сервер будет тратить ресурсы на обработку вхолостую.
Повтор через другой прокси
Разумная стратегия: первая повторная попытка идёт через тот же прокси (возможно, соединение просто моргнуло), вторая — через другой прокси из пула (возможно, проблема в конкретном канале). Ключ при этом не меняется. Тело не меняется. Меняется только маршрут. Так вы отделяете сетевые проблемы от проблем самого запроса и получаете диагностическую информацию: если через второй прокси прошло сразу, дело было в канале.
Пошаговый протокол безопасного повтора
- Прочитать ключ и тело из локальной записи намерения.
- Отправить запрос через текущий прокси с двумя таймаутами.
- При успехе: сохранить результат, завершить.
- При 409 от сервера: подождать указанное время или разумный интервал, повторить с тем же ключом.
- При 422 с кодом несовпадения отпечатка: остановиться, поднять инцидент, не повторять автоматически.
- При ошибке соединения с прокси: сменить прокси, повторить немедленно.
- При 502, 504, обрыве или таймауте: применить политику задержки, повторить с тем же ключом; со второго повтора — через другой прокси.
- После исчерпания попыток: оставить запись в состоянии unknown, передать в очередь сверки (см. Метод 4).
Пункт восемь критичен. Состояние «не знаю, создан ли заказ» — легитимное состояние, и его нельзя молча схлопывать ни в «создан», ни в «не создан».
Метод 4: когда сервер не поддерживает идемпотентные ключи
Идеальный мир заканчивается на первом же партнёрском API, в документации которого слово «идемпотентность» отсутствует. Что делать, если вы клиент, а сервер просто создаёт заказ на каждый POST? Есть несколько техник, от простых до архитектурных.
Естественный ключ в полях запроса
Многие API, не имея формального Idempotency-Key, принимают поле вроде external_order_id, client_reference, merchant_order_number и обещают уникальность по нему в пределах аккаунта. Это и есть идемпотентность под другим именем. Проверьте документацию и, главное, проверьте поведение: отправьте два запроса с одинаковым внешним идентификатором в тестовом окружении и посмотрите, вернётся ли ошибка дубликата или создастся вторая сущность. Обещания в документации и реальное поведение расходятся чаще, чем хотелось бы.
Чтение перед повтором
Если сервер даёт возможность поиска сущностей по вашему внешнему идентификатору или по параметрам (например, список заказов с фильтром по времени и сумме), то перед каждым повтором делайте запрос-проверку: не появился ли уже заказ с моими признаками? Это не даёт строгой гарантии (между проверкой и повтором может проскочить окно), но снижает вероятность дубля на порядок. Схема:
- Первая попытка завершилась неопределённо.
- Подождать интервал, достаточный для завершения обработки на сервере.
- Выполнить GET с фильтром по внешнему идентификатору или уникальной комбинации полей.
- Если заказ найден — зафиксировать его идентификатор, повтор не нужен.
- Если не найден — повторить POST.
Чтобы поиск работал, закладывайте в заказ метку, по которой его можно найти: комментарий, кастомное поле, уникальный номер позиции. Даже если сервер игнорирует её как ключ, он вернёт её в ответе, и вы сможете сверять.
Разделение операции на резервирование и подтверждение
Некоторые API поддерживают двухфазную модель: сначала создаётся черновик или холд (операция, которую можно безопасно повторить или отменить), затем подтверждение по идентификатору черновика. Подтверждение по идентификатору по своей природе идемпотентно: дважды подтвердить один черновик нельзя. Если такая модель доступна, она предпочтительнее одношагового создания даже при наличии ключей, потому что уменьшает окно неопределённости самого рискованного шага.
Паттерн Outbox на вашей стороне
Даже если сервер ничего не гарантирует, вы можете гарантировать, что с вашей стороны каждая операция уйдёт ровно с одним намерением. Транзакционный Outbox — это таблица исходящих операций, куда запись попадает в одной транзакции с бизнес-изменением (например, с переводом корзины в статус «оформляется»). Отдельный процесс-отправитель забирает записи из Outbox и выполняет запросы через прокси. Каждая запись имеет уникальный идентификатор, который вы используете как ключ или как external_id. Даже при падении отправителя посреди работы запись останется в Outbox, и повтор пойдёт с тем же идентификатором.
Сверка как последняя линия обороны
Reconciliation, или сверка, — регулярный процесс, который сравнивает список ваших операций со списком сущностей на стороне партнёра и находит расхождения: заказы, которые есть у партнёра, но не привязаны у вас; операции в статусе unknown; дубли по совпадающим признакам. Сверка не предотвращает дубль, но находит его за минуты, а не за месяц по отчёту бухгалтерии. Для операций через нестабильные каналы это обязательный компонент, а не опция.
Практика: запускать сверку каждые 10–15 минут для операций старше вашего максимального таймаута ретраев, автоматически привязывать найденные сущности к записям в unknown, а обнаруженные дубли передавать в очередь отмены с ручным подтверждением, если сумма выше порога.
Сага и компенсации
Если заказ — часть цепочки действий (резерв склада, оплата, доставка), дубль в одном звене ломает всю цепочку. Паттерн сага предполагает, что для каждого шага есть компенсирующее действие: отмена заказа, возврат оплаты, снятие резерва. Компенсация тоже должна быть идемпотентной, иначе вы будете бороться с дублями отмен. Проектируя интеграцию, сразу выписывайте пары «действие — компенсация» и для обеих проверяйте, что повтор безопасен.
Типичные ошибки: как команды сами создают дубли
Ошибка 1. Ключ генерируется внутри HTTP-клиента
Самая распространённая. Обёртка над HTTP-библиотекой добавляет заголовок Idempotency-Key с новым UUID на каждый вызов. Механизм ретраев внутри той же библиотеки вызывает отправку заново — и получает новый ключ. Внешне всё выглядит правильно: заголовок есть. Фактически защиты нет. Проверяйте по логам сервера или прокси, что при повторах ключ совпадает.
Ошибка 2. Ключ меняется вместе с телом при «исправлении» запроса
Клиент получил 400 из-за невалидного поля, исправил поле и повторил с тем же ключом. Сервер с проверкой отпечатка вернёт 422. Сервер без проверки вернёт закэшированную ошибку 400, и клиент будет биться в стену. Исправленный запрос — это новая операция, ей нужен новый ключ.
Ошибка 3. Проверка ключа через SELECT, потом INSERT
Разобрано выше, но повторим: между чтением и записью успевает проскочить параллельный повтор. Особенно часто это проявляется именно при работе через прокси, потому что клиентские таймауты порождают повторы с интервалом в единицы секунд, а обработка заказа занимает столько же. Только атомарное резервирование.
Ошибка 4. Идемпотентность по IP или сессии
Сервер «запоминает», что с этого IP только что был такой же запрос, и отклоняет повтор. При ротации мобильного прокси повтор приходит с другого адреса, и защита не срабатывает. Обратный вариант тоже плох: легитимные разные заказы с одного прокси-адреса (у вас же много клиентов за одним IP) отклоняются как дубли. Ключ должен быть явным и переданным клиентом.
Ошибка 5. Слишком короткий TTL
Ключи живут пять минут, «чтобы не засорять Redis». Сетевая авария длится двадцать минут. Очередь повторов доходит до операции через полчаса. Ключ забыт, заказ создаётся второй раз. TTL должен покрывать самый длинный реалистичный сценарий отложенного повтора.
Ошибка 6. Кэширование инфраструктурных ошибок
Первая попытка упала с 500 из-за временной недоступности базы. Сервер сохранил 500 как результат по ключу. Все дальнейшие повторы получают 500 из кэша, хотя база давно поднялась. Клиент вынужден менять ключ, теряя связь с исходной операцией. Кэшировать можно только детерминированные результаты.
Ошибка 7. Схлопывание состояния unknown
После исчерпания попыток клиент помечает операцию как failed и позволяет пользователю оформить заказ заново. Но сервер первую операцию выполнил. Пользователь получает два заказа и списание дважды. Состояние unknown должно существовать явно и разрешаться сверкой, а не оптимистичным предположением.
Ошибка 8. Ретрай неидемпотентных операций «потому что так проще»
Универсальный слой ретраев повторяет все запросы одинаково, включая POST без ключей. Это работает до первого сетевого шторма, после которого появляются сотни дублей за час. Слой ретраев должен знать, какие запросы разрешено повторять, и отказываться повторять неидемпотентные без явного ключа.
Ошибка 9. Один ключ на батч
Клиент отправляет массив из ста заказов с одним ключом. Сервер обработал шестьдесят и упал. Повтор с тем же ключом получает 409 или частичный снимок. Как понять, какие сорок нужно создать? Для батчей нужен либо ключ на каждую позицию, либо серверная гарантия атомарности всего батча, либо ответ с поэлементным статусом. Без этого батчи через нестабильный канал — источник хаоса.
Ошибка 10. Отсутствие ключа в логах
Дубль случился, и вы пытаетесь понять, был ли это повтор с тем же ключом (баг сервера) или две разные операции (баг клиента). В логах нет ключа. Расследование превращается в гадание. Ключ должен быть в каждой строке лога по обе стороны и в журнале прокси, если прокси-сервис поддерживает логирование заголовков.
Инструменты и ресурсы для реализации
На стороне клиента
- Библиотеки идентификаторов. Генераторы UUIDv7 и ULID есть для всех основных языков. Выбирайте те, что гарантируют монотонность внутри миллисекунды, если ключи попадают в индексы базы сервера.
- HTTP-клиенты с раздельными таймаутами. Убедитесь, что ваш клиент позволяет задать отдельно таймаут подключения к прокси и таймаут чтения ответа. Большинство современных клиентов это умеют, но по умолчанию часто стоит единый таймаут.
- Очереди с гарантией доставки. Для реализации Outbox подойдёт любая брокерная система с подтверждением обработки. Важно, чтобы идентификатор сообщения был стабилен между повторными доставками — его удобно использовать как основу ключа.
- API управления прокси. У качественных мобильных прокси-сервисов есть программный интерфейс, позволяющий узнать состояние канала, время до ротации, сменить IP по запросу. Интеграция с этим API даёт возможность не начинать критичные операции перед ротацией и осознанно менять маршрут между попытками.
На стороне сервера
- Реляционная база с уникальными индексами. Самый надёжный вариант для хранилища ключей, если объёмы позволяют. Вставка с обработкой конфликта — атомарная операция из коробки.
- Redis или аналог. Для высоконагруженных систем: SET с флагами NX и EX для резервирования, отдельный ключ для снимка ответа. Помните о риске потери данных при сбое узла и настраивайте персистентность.
- Middleware для идемпотентности. Для популярных веб-фреймворков существуют готовые промежуточные слои, реализующие базовый контракт: резервирование, отпечаток, снимок. Проверяйте, как они ведут себя при конкурентных повторах и при падении между выполнением и фиксацией — именно там расходятся хорошие реализации с формальными.
- API-шлюзы. Некоторые шлюзы умеют выполнять дедупликацию по заголовку на входе. Это снимает нагрузку с приложения, но шлюз обычно не знает о бизнес-результате и может кэшировать инфраструктурные ошибки. Используйте как первый фильтр, не как единственную защиту.
Тестирование
- Инъекция сетевых сбоев. Прокси-инструменты для тестирования, которые умеют обрывать соединение после отправки запроса, но до ответа, задерживать ответ дольше таймаута, возвращать 502 и 504. Без таких тестов вы не увидите поведение системы в единственно важном сценарии.
- Конкурентные тесты. Одновременная отправка N запросов с одним ключом. Ожидаемый результат: ровно одна созданная сущность, N-1 ответов 409 или снимков. Любой другой результат — дефект.
- Тест на рестарт посреди операции. Убить процесс после создания заказа, но до фиксации ключа. Проверить, что механизм восстановления зависших записей отработал.
- Тест на ротацию. Первая попытка через один IP, повтор через другой. Проверить, что сервер вернул снимок, а не отклонил повтор эвристикой.
Стандарты и документы
Черновик спецификации IETF по заголовку Idempotency-Key — отправная точка для формулирования контракта: там определены имя заголовка, семантика конфликтов и рекомендуемые коды ответов. Публичная документация крупных платёжных провайдеров — хороший образец того, как описывать контракт для внешних интеграторов: TTL, поведение при несовпадении тела, обработка конкурентных запросов. Раздел про идемпотентные методы в спецификации HTTP-семантики объясняет, почему PUT и DELETE можно повторять, а POST — нет, и это стоит перечитать перед проектированием эндпоинтов.
Кейсы и результаты
Кейс 1. Агрегатор заказов и 47 дублей в месяц
Компания-агрегатор передавала заказы в систему логистического партнёра через пул мобильных прокси с ротацией каждые пять минут. Объём — около 12 тысяч заказов в сутки. Идемпотентных ключей не было: партнёрский API их не документировал. Дубли обнаруживались раз в месяц по финансовой сверке, каждый обходился в среднем в 900 рублей на отмену, возврат и ручную работу.
Диагностика по логам прокси показала: 0,4% запросов завершались обрывом соединения после отправки тела и до получения ответа, преимущественно в минуты ротации. Повтор шёл через три секунды, и в 30% случаев первая попытка к этому моменту уже была выполнена. Расчёт сходился с наблюдаемыми дублями.
Решение в три шага. Во-первых, выяснилось, что API партнёра принимает поле external_id и отклоняет дубликаты по нему, хотя в документации это упоминалось одной строкой. Поле стали заполнять стабильным идентификатором из локального Outbox. Во-вторых, окна ротации синхронизировали с отправкой: за 15 секунд до ротации новые заказы не отправлялись. В-третьих, добавили сверку каждые 10 минут. Результат за квартал: ноль дублей, число повторов снизилось на 70% за счёт синхронизации с ротацией, среднее время оформления выросло на 1,2 секунды из-за ожидания окон — приемлемая цена.
Кейс 2. Платёжный сервис и конкурентные повторы
Финтех-сервис реализовал идемпотентность на своей стороне: заголовок принимался, ключ сохранялся в базе, при повторе возвращался снимок. Дубли всё равно появлялись, редко, но регулярно: примерно один на 40 тысяч операций. Расследование показало, что проверка ключа делалась через чтение, а затем через запись, и клиенты с агрессивными таймаутами (два повтора в течение секунды через разные прокси) попадали в окно между ними.
Заменили на вставку с уникальным индексом и добавили состояние in_progress с ответом 409 и заголовком Retry-After в одну секунду. Добавили метрику конкурентных повторов. Она показала неожиданное: 2% всех операций получают хотя бы один 409, то есть клиенты повторяют гораздо агрессивнее, чем предполагалось. Сервис обновил документацию с рекомендациями по таймаутам, и через два месяца доля 409 снизилась до 0,3%. Дублей — ноль за полгода.
Кейс 3. Маркетплейс-интеграция и батчи
Продавец загружал остатки и цены на маркетплейс батчами по 500 позиций через прокси. Идемпотентность батча была на уровне всего запроса. При обрыве соединения повтор либо отклонялся (батч в процессе), либо возвращал снимок частичного результата, из которого не было понятно, какие позиции обновились. Продавец делал вывод «не обновилось» и грузил заново, что создавало гонки между старым и новым батчем.
Решение: перейти на батчи с поэлементными идентификаторами операций и запрашивать поэлементный статус после неопределённого завершения. Размер батча снизили до 100 позиций, чтобы время обработки не превышало таймаут. Число «зависших» обновлений упало с десятков в день до нуля, а расхождения остатков, ранее регулярно приводившие к отменам заказов покупателей, исчезли.
Кейс 4. Автоматизированный агент и цепные повторы
Тренд 2026 года: всё больше интеграций выполняются автономными агентами на базе больших языковых моделей, которые вызывают API по инструкциям. Команда внедрила такого агента для оформления закупок у поставщиков. Агент при неопределённом ответе «рассуждал» и решал повторить операцию, генерируя новый запрос. Ключей не было, поскольку агент формировал вызов каждый раз заново. За первую неделю — 11 дублей закупок.
Исправление: агенту запретили формировать запросы создания напрямую. Он создаёт запись намерения в Outbox через внутренний инструмент, а отправку выполняет детерминированный сервис с ключами и сверкой. Агент получает только финальный статус. Дубли исчезли, а заодно появилась полная трассировка, кто и почему инициировал каждую закупку. Вывод общий: автономные системы с способностью к ретраям — новый и мощный источник дублей, и барьер идемпотентности для них обязателен.
FAQ: сложные вопросы об идемпотентности и повторах
Нужен ли идемпотентный ключ для PUT и DELETE, если они идемпотентны по спецификации?
Формально нет: повтор PUT с тем же телом даст то же состояние. Но есть нюансы. Если PUT возвращает 201 при создании и 200 при обновлении, повтор вернёт другой статус, и клиент может интерпретировать его иначе. DELETE при повторе вернёт 404 вместо 204, что часто обрабатывается как ошибка. Ключ с снимком ответа делает поведение предсказуемым. Кроме того, если PUT вызывает побочные эффекты (отправку уведомления, запись в аудит), они выполнятся повторно. Идемпотентность метода не равна идемпотентности всех побочных эффектов.
Что делать, если сервер вернул 409 in_progress, а первая попытка на самом деле умерла?
Это ответственность сервера: у него должен быть механизм восстановления зависших записей с порогом по времени. Клиенту стоит ждать 409 не бесконечно, а ограниченное число раз (например, до двух минут), затем переводить операцию в unknown и передавать в сверку. Если сервер систематически держит in_progress дольше разумного, это дефект реализации, о котором нужно сообщить владельцу API.
Как быть с ключом, если запрос идёт через несколько прокси в цепочке?
Никак специально: ключ передаётся в заголовке и прозрачно проходит через любую цепочку. Единственное, что стоит проверить, — не удаляет ли какой-то промежуточный узел нестандартные заголовки. Некоторые корпоративные шлюзы фильтруют заголовки по белому списку. Простой тест: отправить запрос через всю цепочку на собственный отладочный эндпоинт и убедиться, что заголовок дошёл.
Можно ли использовать хеш тела запроса как ключ и не хранить ничего у клиента?
Можно, но с оговорками. Два разных заказа с одинаковым содержимым (один и тот же товар, та же сумма, тот же покупатель) получат один ключ и второй будет отклонён как повтор. Чтобы избежать этого, в тело добавляют уникальный компонент — идентификатор корзины или локальный порядковый номер. Тогда хеш от тела становится детерминированным ключом операции. Такой подход удобен для клиентов без надёжного локального хранилища, но требует строгой нормализации тела: изменение порядка полей в JSON изменит хеш.
Как долго ждать перед повтором, чтобы сервер успел завершить первую попытку?
Это вопрос политики повторов, но с точки зрения контракта важно одно: если сервер поддерживает in_progress с 409, ждать «на глазок» не нужно — сервер сам сообщит, что операция ещё выполняется. Если сервер такого состояния не имеет, интервал перед повтором должен превышать 99-й процентиль времени обработки операции на сервере. Узнать его можно из документации, из метрик успешных запросов или эмпирически на тестовом стенде.
Стоит ли делать идемпотентными операции чтения?
GET идемпотентен по определению, ключ ему не нужен. Но есть исключение: «чтение с побочным эффектом», например, GET, который помечает уведомление прочитанным или списывает лимит. Это архитектурный запах; такие операции лучше переделать в POST с ключом, чем прикручивать идемпотентность к GET.
Что делать с ключами при миграции или смене версии API?
Включайте версию эндпоинта в область действия ключа на сервере. Тогда ключ, использованный в v1, не столкнётся с тем же ключом в v2. Для клиента правило простое: миграция — это новые операции с новыми ключами, старые ключи не переносятся. Если операция была в unknown на момент миграции, сначала разрешите её сверкой, затем мигрируйте.
Как объяснить бизнесу, зачем тратить спринт на идемпотентность, если дублей «почти не бывает»?
Посчитайте стоимость одного дубля: отмена, возврат, поддержка, репутация, иногда штрафы партнёра. Умножьте на наблюдаемую частоту. Затем покажите, что частота растёт нелинейно при сетевых инцидентах: в спокойный день ноль дублей, в день аварии у оператора связи — сотни за час. Идемпотентность — страховка с известной премией и неизвестным, но потенциально огромным выигрышем. Плюс она даёт побочный эффект: возможность агрессивно повторять запросы без страха, что ускоряет восстановление после сбоев.
Повышает ли идемпотентность нагрузку на сервер?
Незначительно: одна дополнительная запись и одно чтение на операцию. Зато она снижает нагрузку в аварийных сценариях, потому что повтор возвращает снимок за миллисекунды вместо полной обработки заказа. При шторме повторов сервер с идемпотентностью выдерживает нагрузку лучше, чем без неё, — это контринтуитивно, но подтверждается практикой.
Заключение: контракт вместо надежды
Давайте соберём главное. Любая сеть доставляет запросы по принципу «хотя бы один раз». Прокси — особенно мобильные, с ротацией и радиоканалом — делают повторы не редкостью, а нормой. Политика ретраев отвечает на вопрос «когда и как повторять». Идемпотентность отвечает на вопрос «почему повтор не сломает ничего». Без второго ответа первый опасен.
Безопасный повтор держится на трёх опорах. Ключ операции, рождённый до первой попытки и живущий в вашей базе, а не в HTTP-клиенте. Серверный контракт с атомарным резервированием, состоянием in_progress, отпечатком тела, снимком ответа и разумным TTL. Сверка как последняя линия обороны для операций, застрявших в неопределённости. Если сервер контракта не даёт, роль ключа берёт на себя естественный идентификатор, а роль хранилища — ваш Outbox.
Что делать дальше, прямо сегодня:
- Найдите в своих интеграциях все POST-операции, которые повторяются автоматически. Для каждой ответьте: есть ли ключ, где он генерируется, совпадает ли при ретраях.
- Прочитайте документацию партнёрских API на предмет полей external_id и заголовка Idempotency-Key. Проверьте поведение в тестовом контуре двумя одинаковыми запросами.
- Добавьте состояние unknown в модель операций и процесс сверки для него.
- Если владеете сервером, прогоните три теста: конкурентные повторы, падение между выполнением и фиксацией, повтор с другого IP.
- Выведите на дашборд соотношение повторов и уникальных операций. Это ваш индикатор здоровья канала через прокси.
Идемпотентность — редкий случай, когда инженерная дисциплина напрямую конвертируется в спокойствие бизнеса. Один раз спроектированный контракт годами защищает от дублей, штормов повторов и ночных звонков из бухгалтерии. И, честно говоря, есть особое удовольствие в том, чтобы смотреть на график из тысяч повторов через нестабильный канал и видеть в колонке дублей уверенный ноль.