Ключ идемпотентности — это заданный клиентом идентификатор запроса, благодаря которому повторная попытка после тайм-аута или ошибки возвращает исходный результат, не отправляя сообщение второй раз.
Соединение может оборваться уже после того, как сервер выполнил запрос, но до того, как клиент получил ответ. Без идемпотентности повторная попытка рискует отправить сообщение дважды, а отказ от повтора оставляет результат неизвестным. Ключ решает эту проблему: сервер узнаёт повторный запрос, возвращает первоначальный ответ и не создаёт новое сообщение.
Ключ стоит формировать из собственного бизнес-идентификатора — например номера заказа, пользователя и номера попытки. Тогда повторы из разных процессов будут распознаны как один запрос. При повторной отправке нужно использовать прежний ключ, а не создавать новый.
В SMSMeteor: любой POST-запрос принимает Idempotency-Key; тот же ключ с той же полезной нагрузкой в течение 24 часов возвращает исходный ответ с Idempotent-Replayed: true, а с другой полезной нагрузкой — ошибку 409 idempotency_conflict.