Дубли заказов при работе с API: причины и защита

Почему дубли появляются после одного действия

Владелец панели может нажать кнопку один раз и увидеть несколько одинаковых заказов: на подписчиков, просмотры, реакции или другую услугу. Обычно проблема не в самом клике, а в цепочке между клиентом, API, базой данных и поставщиком.

С точки зрения сервера «один запрос» не всегда один. Клиент мог не получить ответ, повторить отправку, а первая операция уже успела сохраниться. Иногда заказ создаётся один раз в базе панели, но дважды уходит поставщику. Это разные сценарии, и исправляются они по-разному.

Таймаут не означает, что заказ не создан

Самая частая причина — клиент ждёт ответ ограниченное время. Сервер принимает запрос, создаёт заказ, но отвечает позже установленного таймаута. Клиент считает операцию неуспешной и отправляет её повторно.

В результате первый заказ уже есть в базе, а второй запрос создаёт ещё один. Особенно часто это происходит при медленном ответе внешнего API, перегруженной очереди или нестабильном соединении между сервисами.

Таймаут говорит только об отсутствии ответа, а не об отсутствии обработки запроса.

Автоматические повторы на стороне клиента

Библиотеки для HTTP-запросов, фоновые задачи и интеграционные сервисы нередко повторяют запрос автоматически. Поводом может стать ошибка соединения, код ответа сервера, обрыв сети или слишком долгий ответ.

Повтор сам по себе полезен: он снижает число потерянных заказов при временных сбоях. Недостаток такого подхода — без защиты от повторной обработки он превращает любую нестабильность сети в дубли.

• повтор может запускаться в коде сайта или бота;
• задачу может перезапускать очередь;
• запрос может повторять прокси или интеграционный модуль;
• оператор может вручную отправить заказ повторно после ошибки.

Повторный запрос приходит раньше первого ответа

Иногда два одинаковых запроса действительно доходят до API почти одновременно. Например, пользователь дважды отправил форму, фронтенд не заблокировал кнопку или фоновая задача стартовала повторно до завершения первой.

Если обработчик сначала проверяет наличие заказа, а затем создаёт его, две параллельные операции могут пройти проверку одновременно. Каждая увидит, что заказа ещё нет, и каждая добавит новую запись.

Такую ситуацию называют гонкой данных. Простая предварительная проверка в коде не защищает от неё полностью. Недостаток проверки без ограничения на уровне базы — она ломается при параллельной нагрузке.

Заказ записался, но ответ API потерялся

Запрос проходит несколько этапов: сервер получает данные, создаёт запись, ставит задачу в очередь, отправляет ответ. Сбой возможен между любыми из них. Например, база уже подтвердила создание заказа, но соединение оборвалось до передачи ответа клиенту.

Клиент не знает, был ли заказ принят, и повторяет операцию. API без отдельного механизма проверки воспринимает запрос как новый. В журнале это часто выглядит так, будто сервис создал два заказа «сам», хотя у него было два входящих обращения.

Идемпотентный ключ для создания заказа

Для операций создания нужен уникальный ключ идемпотентности. Клиент генерирует его перед первой отправкой и передаёт вместе с параметрами заказа. При повторе из-за таймаута или ошибки используется тот же ключ.

API сохраняет ключ вместе с результатом обработки. Если приходит запрос с уже известным ключом, сервер не создаёт новый заказ, а возвращает результат первого обращения: идентификатор заказа, его статус или ранее сформированную ошибку.

Один ключ должен соответствовать одной бизнес-операции, а не одному HTTP-соединению.

Недостаток метода — ключи нужно хранить, очищать по правилам и проверять на стороне API. Если генерировать новый ключ при каждом повторе, защита не сработает. Если использовать один ключ для разных заказов, часть новых операций будет ошибочно отклонена.

Уникальность должна контролироваться базой данных

Идемпотентность лучше дополнять ограничением уникальности в базе. Для этого выбирают комбинацию, которая однозначно описывает заказ: внутренний идентификатор клиента, ключ идемпотентности, тип услуги и другие нужные поля.

База данных должна отклонять вторую запись, даже если два обработчика дошли до создания одновременно. После конфликта API возвращает существующий заказ, а не ошибку без пояснения.

Недостаток жёсткого уникального ограничения — его нельзя строить только на ссылке или username. Клиент может осознанно заказать одну услугу на тот же канал несколько раз. Слишком широкое ограничение заблокирует нормальные повторные покупки.

Очередь может доставить задачу больше одного раза

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

Для очереди это нормальный способ не потерять задачу. Для создания заказа без идемпотентности — источник дублей. Идентификатор задачи или отдельный ключ операции нужно передавать до конечного обработчика, включая модуль отправки заказа поставщику.

Недостаток отключения повторной доставки — при падении воркера часть заказов может пропасть. Безопаснее принимать возможные повторы и делать обработчик устойчивым к ним.

Дубли возникают между панелью и поставщиком

Внутренний заказ может быть создан один раз, но запрос к внешнему API отправлен дважды. Причина та же: панель не получила ответ от поставщика и решила повторить отправку. Если поставщик успел принять первый запрос, на его стороне появятся две одинаковые заявки.

Нужна отдельная привязка внутреннего заказа к внешнему: идентификатор отправки, ключ идемпотентности или сохранённый ответ поставщика. Нельзя считать, что защита на входе в собственную панель автоматически защитит исходящие вызовы.

Недостаток сверки со сторонним API — не каждый поставщик поддерживает поиск по внешнему ключу. Тогда приходится фиксировать попытки отправки и отдельно разбирать неопределённые статусы.

Вебхук не должен создавать новый заказ

Вебхуки сообщают об изменениях: заказ принят, запущен, выполнен, отменён или требует проверки. Ошибка возникает, когда обработчик вебхука воспринимает уведомление как команду создать заказ заново.

Один и тот же вебхук может прийти повторно. Отправитель повторяет доставку, если не получил подтверждение, а уведомления иногда поступают не по порядку. Обработчик должен находить существующий заказ по внешнему идентификатору и обновлять статус.

Недостаток обработки вебхуков только по времени получения — позднее уведомление может перезаписать актуальный статус устаревшим. Нужны идентификатор события, версия статуса или понятные правила переходов.

Какие записи помогут найти источник дублей

Для расследования недостаточно видеть только два номера заказов. Нужны данные о каждом этапе обработки: время запроса, ключ идемпотентности, идентификатор клиента, параметры заказа, номер фоновой задачи, ответ внешнего API и попытки повторной отправки.

• сопоставляйте дубли по ключу операции, а не только по ссылке;
• проверяйте, были ли одинаковые запросы в журнале входящего API;
• смотрите, повторялась ли задача в очереди;
• отделяйте создание внутреннего заказа от отправки поставщику;
• сохраняйте внешний идентификатор заявки сразу после получения ответа.

Недостаток слишком коротких логов — источник проблемы исчезает раньше, чем его успевают разобрать. Недостаток чрезмерного логирования — в записи могут попасть токены, персональные данные и другие чувствительные поля, поэтому их нужно маскировать.

Как обрабатывать неопределённый результат запроса

После таймаута нельзя сразу создавать заказ повторно с новыми данными. Сначала API должен проверить операцию по ключу идемпотентности или клиентскому идентификатору. Если заказ найден, возвращается его текущее состояние. Если обработка ещё идёт, клиент получает статус ожидания.

1. Создать ключ операции до первого запроса.
2. Отправлять тот же ключ при каждом повторе.
3. Сохранить ключ и заказ в одной защищённой операции базы данных.
4. Передавать идентификатор операции в очередь и внешний API.
5. Возвращать ранее созданный заказ при повторном обращении.

Такой сценарий требует доработки API и клиентской интеграции. Его недостаток — сложнее отладка и больше состояний заказа, зато повторная доставка запроса перестаёт автоматически означать повторную покупку.