Ключ идемпотентности — это заданный клиентом идентификатор запроса, благодаря которому повторная попытка после тайм-аута или ошибки возвращает исходный результат, не отправляя сообщение второй раз.
Сеть подводит в самый неподходящий момент: когда сервер уже выполнил действие, а клиент ещё не узнал об этом. Запрос, завершившийся тайм-аутом, мог отправить сообщение, а мог и не отправить, и клиент не может понять, что произошло. Без идемпотентности безопасная реакция — ничего не делать, а соблазнительная — повторить запрос — грозит дубликатом. С ключом идемпотентности клиент может спокойно повторять запрос: сервер узнаёт ключ, возвращает результат первой попытки и ничего нового не отправляет.
Заголовок Idempotency-Key — соглашение, которое популяризировали платёжные API и которое с тех пор получило широкое распространение. Серверы хранят ключи ограниченное время, и многие отклоняют ключ, который пришёл повторно с другой полезной нагрузкой: это говорит об ошибке в клиенте, а не о повторной попытке. Ключ следует формировать из собственного бизнес-идентификатора — номера заказа плюс события или пользователя плюс попытки, — чтобы повторы из разных процессов или с разных серверов совпадали так, как нужно. Его нужно создать до первой попытки, сохранить вместе с заданием и без изменений использовать при каждом повторе.
Пример
Условный магазин отправляет уведомление об отгрузке заказа 4821 с ключом order-4821-shipped. Первый POST-запрос завершается тайм-аутом. Повторный запрос с тем же ключом возвращает исходные идентификатор и статус сообщения; клиент получает одно SMS, а с учётной записи списывается оплата за одно. Если бы при повторе использовался новый ключ, клиент получил бы два.
Типичные ошибки
- Генерировать новый случайный ключ при каждом повторе, что лишает механизм смысла.
- Использовать слишком общий ключ, например только идентификатор пользователя: тогда последующие, уже другие сообщения принимаются за повторы и не отправляются.
- Создавать ключ внутри цикла повторов вместо того, чтобы сохранять его вместе с заданием.
В SMSMeteor: любой POST-запрос принимает Idempotency-Key — строку длиной до 128 символов, которую вы выбираете сами. Тот же ключ и та же полезная нагрузка в течение 24 часов: возвращается исходный ответ с заголовком Idempotent-Replayed: true. Тот же ключ, другая полезная нагрузка: 409 idempotency_conflict. Это важно, потому что сообщение тарифицируется, как только передано оператору связи, и дубликат означал бы повторное списание. После ответа 429 выждите время, указанное в Retry-After, и повторите запрос с тем же ключом. Подробности — в справочнике API, а тестовый ключ позволяет отрепетировать тайм-ауты и повторы, ничего не отправляя.
