Перейти к содержимому
← Все статьи
6 мин чтения

Идемпотентность API: как обрабатывать повторные запросы без дублей

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

Почему сетевые таймауты приводят к дублированию записей

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

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

Заголовок Idempotency-Key и жизненный цикл запроса

Для безопасного выполнения операций изменения состояния клиент генерирует уникальный идентификатор, например UUID, и передаёт его в HTTP-заголовке Idempotency-Key. Сервер проверяет наличие записи с данным ключом до выполнения бизнес-логики.

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

Уникальные ограничения в базе данных как главная защита

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

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

  • Создание уникального индекса по составному ключу из идентификатора клиента и значения Idempotency-Key.
  • Атомарная фиксация статуса обработки: в процессе, успешно или с ошибкой.
  • Сохранение кода и тела ответа для возврата клиенту при повторных вызовах.

Обработка входящих вебхуков и повторные уведомления

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

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

Экспоненциальная задержка и джиттер при повторах на клиенте

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

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

Сценарий защиты от повторного создания заказа

Чтобы исключить дублирование заказа, клиент формирует уникальный ключ транзакции и отправляет запрос на сервер. Сервер открывает транзакцию базы данных и проверяет статус ключа перед выполнением заказа.

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

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

Частые вопросы

Не нашли ответ — спросите на созвоне или в Telegram.

Сколько времени нужно хранить ключи идемпотентности?

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

Что делать, если пришёл тот же ключ, но с другим телом запроса?

Сервер должен вычислять хэш полезной нагрузки запроса и сравнивать его с сохранённым значением. Если ключ совпадает, а параметры изменились, обработку следует прервать с ошибкой HTTP 422 Unprocessable Entity или HTTP 409 Conflict, сообщая о конфликте параметров.

Являются ли методы PUT и DELETE идемпотентными по умолчанию?

По спецификации HTTP методы PUT и DELETE обязаны быть идемпотентными. Многократный вызов корректного PUT-запроса приводит к одинаковому состоянию ресурса, а повторный вызов DELETE оставляет ресурс удалённым, даже если последующие вызовы возвращают код HTTP 404.

Связанная услуга

Интеграции 1С, CRM и внешних API

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

Об услуге
Другие статьи
6 мин чтения

Интеграция с 1С, amoCRM и ERP: архитектура надёжного обмена данными

Интеграция с 1С, amoCRM и маркетплейсами через API: организация очередей, обработка лимитов, идемпотентность запросов и сквозной мониторинг обмена данными.

Читать статью: Интеграция с 1С, amoCRM и ERP: архитектура надёжного обмена данными →
6 мин чтения

Безопасность вебхуков: подпись, верификация и защита входящих запросов

Безопасность вебхуков: подпись HMAC, проверка в постоянное время, защита от повторов по timestamp и безопасная ротация секретов.

Читать статью: Безопасность вебхуков: подпись, верификация и защита входящих запросов →
Контакт

Обсудим вашу задачу?

Тридцать минут созвона — и у вас есть понимание архитектуры, сроков и формата работы. Без обязательств.

Или напишите в Telegram →Читайте наш канал в Telegram →

Укажите Telegram или email, чтобы мы могли ответить.

Отвечаем в течение 15 минут.