Ключи идемпотентности: как не списать деньги дважды, когда клиент повторяет запрос
Ответ потерялся, клиент повторил запрос, и деньги списались дважды. Разбираем Idempotency-Key, unique constraint в PostgreSQL и одну транзакцию на списание и ответ: полная реализация на Django и сравнение со Stripe.
Пользователь нажимает «Оплатить» в мобильном приложении. Запрос доходит до сервера, с кошелька списывается 150 000 сумов, создаётся запись Payment. А ответ теряется по дороге назад: телефон заехал в лифт, мобильная сеть переключилась на Wi-Fi или балансировщик упёрся в 30-секундный таймаут. Приложение показывает «Ошибка сети». Пользователь жмёт ещё раз. Да и само приложение, скорее всего, сделает автоматический retry.
В итоге сервер выполняет один и тот же платёж дважды, а клиент платит 300 000. Это обычная сетевая ситуация: клиент не может знать, запрос не выполнился или выполнился, но ответ потерялся. В обоих случаях он видит одно и то же: таймаут.
В этой статье разберём стандартное решение — ключи идемпотентности (idempotency keys): заголовок Idempotency-Key, хранение ключа вместе с хешем запроса и ответом, как unique constraint в PostgreSQL ведёт себя при параллельных запросах, срок жизни ключа и сравнение с подходом Stripe. В конце — полностью рабочая реализация на Django + PostgreSQL.
Что такое идемпотентность и почему у POST её нет
Операция идемпотентна, если выполнить её один раз или десять — результат одинаковый. В семантике HTTP идемпотентными определены GET, PUT, DELETE: отправьте PUT /users/7 с одними и теми же данными дважды, и состояние не изменится. POST не идемпотентен: каждый POST /payments/ создаёт новый платёж.
Чтобы повтор стал безопасным, серверу нужно сказать «это тот же самый запрос, а не новый». Для этого клиент генерирует уникальный ключ на каждое намерение и передаёт его в заголовке:
KEY=$(uuidgen)
curl -X POST https://api.example.com/v1/payments/ \
-H "Authorization: Bearer $TOKEN" \
-H "Idempotency-Key: $KEY" \
-H "Content-Type: application/json" \
-d '{"order_id": 4812, "amount": 15000000}'
# Timeout? Send exactly the same request with the same $KEY again.
Увидев ключ впервые, сервер выполняет запрос и сохраняет ответ вместе с ключом. Если с этим ключом приходит повтор, сервер ничего не выполняет заново, а возвращает сохранённый ответ. С точки зрения клиента retry теперь безопасен: что бы ни случилось, деньги спишутся один раз.
Важный момент: ключ создаётся не на каждую попытку, а на каждое намерение. В момент нажатия «Оплатить» генерируется один UUID, и все повторы идут с ним. Если генерировать новый ключ на каждый retry, весь механизм теряет смысл.
Где ломается наивный подход
Первое, что приходит в голову:
# WRONG: check-then-act
def create_payment(request):
key = request.headers.get("Idempotency-Key")
existing = IdempotencyKey.objects.filter(user=request.user, key=key).first()
if existing:
return JsonResponse(existing.response_body, status=existing.response_code)
code, body = charge_wallet(request.user, amount, order_id) # money moves here
IdempotencyKey.objects.create(
user=request.user, key=key, response_code=code, response_body=body
)
return JsonResponse(body, status=code)
Здесь три проблемы.
1. Гонка (race condition). Два запроса приходят с разницей в миллисекунды (например, клиент сделал retry после таймаута, а первый запрос ещё выполняется). Оба делают filter().first(), оба получают None, оба списывают деньги. Классический «check-then-act»: между проверкой и действием вклинивается другой процесс. В прошлых статьях мы говорили о select_for_update, но здесь он не поможет: нельзя заблокировать строку, которой ещё нет.
2. Деньги списаны, ключ не сохранён. charge_wallet и create выполняются отдельно. Если процесс умрёт между ними (OOM, рестарт воркера во время деплоя), деньги списаны, а ключа нет. Следующий retry спишет ещё раз.
3. Тело запроса не проверяется. Если клиент по ошибке отправит тот же ключ с другой суммой, сервер вернёт старый ответ, и клиент будет думать, что оплачено 100 000, хотя на самом деле 150 000. Такую ошибку нужно явно показывать, а не молча проглатывать.
Блокировка кнопки на фронтенде тоже не решение: она спасает от двойного клика, но не от сетевых повторов, прокси или собственной retry-логики приложения.
Механизм: unique constraint как арбитр
Самый надёжный способ убрать гонку — отдать вопрос «кто первый» не коду приложения, а базе данных. С unique constraint на (user_id, key) PostgreSQL никогда не сохранит две строки с одинаковым ключом.
Интереснее, как PostgreSQL ведёт себя при параллельных транзакциях. Если транзакция A вставила ключ, но ещё не сделала COMMIT, INSERT с тем же ключом в транзакции B не падает сразу, а ждёт: ей нужно узнать, закоммитит A или откатит. Это легко проверить в двух окнах psql:
-- psql session A
BEGIN;
INSERT INTO payments_idempotencykey
(user_id, key, request_hash, status, locked_at, created_at)
VALUES (1, 'k-1', 'abc', 'started', now(), now());
-- psql session B: this statement hangs until A finishes
INSERT INTO payments_idempotencykey
(user_id, key, request_hash, status, locked_at, created_at)
VALUES (1, 'k-1', 'abc', 'started', now(), now());
-- session A
COMMIT;
-- session B now fails:
-- ERROR: duplicate key value violates unique constraint "uniq_idem_user_key"
-- (if A had done ROLLBACK instead, B's INSERT would succeed)
То есть unique-индекс гарантирует, что из двух запросов «победит» ровно один, а второй получит IntegrityError. Никаких ручных блокировок.
Не проверяйте ключ — захватывайте его. Прошёл INSERT — запрос ваш; получили IntegrityError — кто-то успел раньше.
Отсюда обработка запроса в три шага:
- Захват ключа. Вставляем строку со статусом
startedв отдельной короткой транзакции и сразу коммитим. Остальные запросы тут же видят, что ключ занят. - Выполнение работы. Списание денег и запись ответа в ключ — в одной транзакции. Сохраняется либо всё, либо ничего.
- Ответ на повтор. Ключ
completed— возвращаем сохранённые статус и тело.started—409 Conflict. Хеш не совпал —422.
Реализация: Django + PostgreSQL
Начнём с моделей. Суммы храним целым числом в тийинах (об этом была отдельная статья):
# payments/models.py
from django.conf import settings
from django.db import models
class IdempotencyKey(models.Model):
class Status(models.TextChoices):
STARTED = "started"
COMPLETED = "completed"
user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
key = models.CharField(max_length=255)
request_hash = models.CharField(max_length=64)
status = models.CharField(max_length=16, choices=Status, default=Status.STARTED)
response_code = models.PositiveSmallIntegerField(null=True)
response_body = models.JSONField(null=True)
locked_at = models.DateTimeField(null=True)
created_at = models.DateTimeField(auto_now_add=True)
class Meta:
constraints = [
models.UniqueConstraint(fields=["user", "key"], name="uniq_idem_user_key"),
]
indexes = [models.Index(fields=["created_at"])]
class Wallet(models.Model):
user = models.OneToOneField(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
balance = models.PositiveBigIntegerField(default=0) # in tiyin
class Payment(models.Model):
user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.PROTECT)
order_id = models.PositiveBigIntegerField(unique=True) # second line of defense
amount = models.PositiveBigIntegerField() # in tiyin
created_at = models.DateTimeField(auto_now_add=True)
Обратите внимание на unique=True у Payment.order_id. Если в домене есть естественный ключ (один заказ оплачивается один раз), защитите и его констрейнтом. Idempotency key — общий механизм, естественный unique constraint — вторая линия обороны.
Теперь главное — захват и проверка ключа:
# payments/idempotency.py
import hashlib
import json
from datetime import timedelta
from django.db import IntegrityError, OperationalError, transaction
from django.utils import timezone
from .models import IdempotencyKey
LOCK_TIMEOUT = timedelta(seconds=60) # must be longer than your worker timeout
class IdempotencyConflict(Exception):
"""The same key is being processed right now."""
class IdempotencyMismatch(Exception):
"""The same key was used with a different request."""
def request_fingerprint(method: str, path: str, data: dict) -> str:
canonical = json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
return hashlib.sha256(f"{method}:{path}:{canonical}".encode()).hexdigest()
def acquire(user, key: str, fingerprint: str) -> tuple[IdempotencyKey, bool]:
"""Return (record, replay). replay=True means a stored response exists."""
now = timezone.now()
# Step 1: try to claim the key. Short transaction, committed immediately.
try:
with transaction.atomic():
record = IdempotencyKey.objects.create(
user=user, key=key, request_hash=fingerprint, locked_at=now
)
return record, False
except IntegrityError:
pass # the key already exists (committed by someone else)
# Step 2: the key exists. Inspect it without waiting on a busy row.
try:
with transaction.atomic():
record = IdempotencyKey.objects.select_for_update(nowait=True).get(
user=user, key=key
)
if record.request_hash != fingerprint:
raise IdempotencyMismatch()
if record.status == IdempotencyKey.Status.COMPLETED:
return record, True
if record.locked_at and now - record.locked_at < LOCK_TIMEOUT:
raise IdempotencyConflict()
# Stale or released lock: take it over.
record.locked_at = now
record.save(update_fields=["locked_at"])
return record, False
except OperationalError:
# nowait=True: another transaction holds the row lock right now
raise IdempotencyConflict()
Несколько деталей:
- Хеш считается от канонического JSON (
sort_keys=True), чтобы{"a":1,"b":2}и{"b":2,"a":1}давали одно и то же. В хеш входят метод и путь: использовать ключ на другом эндпоинте — тоже ошибка. nowait=True. Если строку прямо сейчас держит другая транзакция (то есть первый запрос именно в этот момент списывает деньги), мы не ждём, а сразу отвечаем409. Без этого второй запрос занимал бы воркер и соединение, дожидаясь первого.locked_at— на случай, когда процесс умер. Если ключ висит вstartedдольшеLOCK_TIMEOUT, считаем, что владелец его бросил, и забираем себе.
Логика списания простая, кошелёк блокируется через select_for_update:
# payments/services.py
from django.db.models import F
from .models import Payment, Wallet
def charge_wallet(user, amount: int, order_id: int) -> tuple[int, dict]:
"""Must be called inside transaction.atomic()."""
wallet = Wallet.objects.select_for_update().get(user=user)
if wallet.balance < amount:
return 402, {"error": "insufficient_funds"}
wallet.balance = F("balance") - amount
wallet.save(update_fields=["balance"])
payment = Payment.objects.create(user=user, order_id=order_id, amount=amount)
return 201, {"payment_id": payment.pk, "order_id": order_id, "amount": amount}
Заметьте: «недостаточно средств» возвращается не исключением, а обычным ответом. Это детерминированный бизнес-результат, и его тоже надо сохранить: повтор с тем же ключом должен снова получить 402.
И наконец, view:
# payments/views.py
import json
from django.contrib.auth.decorators import login_required
from django.db import transaction
from django.http import JsonResponse
from django.views.decorators.http import require_POST
from .idempotency import (
IdempotencyConflict, IdempotencyMismatch, acquire, request_fingerprint,
)
from .models import IdempotencyKey
from .services import charge_wallet
def replayed(record: IdempotencyKey) -> JsonResponse:
response = JsonResponse(record.response_body, status=record.response_code)
response["Idempotent-Replayed"] = "true"
return response
@transaction.non_atomic_requests
@login_required
@require_POST
def create_payment(request):
key = request.headers.get("Idempotency-Key", "")
if not 1 <= len(key) <= 255:
return JsonResponse({"error": "idempotency_key_required"}, status=400)
try:
data = json.loads(request.body)
amount, order_id = int(data["amount"]), int(data["order_id"])
except (ValueError, KeyError, TypeError):
return JsonResponse({"error": "invalid_request"}, status=400)
fingerprint = request_fingerprint(request.method, request.path, data)
try:
record, replay = acquire(request.user, key, fingerprint)
except IdempotencyMismatch:
return JsonResponse({"error": "idempotency_key_reused"}, status=422)
except IdempotencyConflict:
return JsonResponse({"error": "request_in_progress"}, status=409)
if replay:
return replayed(record)
try:
with transaction.atomic():
# Holding this row lock until COMMIT prevents a double run
# even if a slow request's lock was taken over as "stale".
locked = IdempotencyKey.objects.select_for_update().get(pk=record.pk)
if locked.status == IdempotencyKey.Status.COMPLETED:
return replayed(locked)
code, body = charge_wallet(request.user, amount, order_id)
locked.status = IdempotencyKey.Status.COMPLETED
locked.response_code = code
locked.response_body = body
locked.save(update_fields=["status", "response_code", "response_body"])
except Exception:
# Everything above was rolled back, so a retry is safe: release the key.
IdempotencyKey.objects.filter(
pk=record.pk, status=IdempotencyKey.Status.STARTED
).update(locked_at=None)
raise
return JsonResponse(body, status=code)
Ключевое место здесь — select_for_update() во внутренней транзакции. Представьте, что первый запрос работал очень медленно, LOCK_TIMEOUT истёк, и второй запрос забрал ключ как «протухший». Второй проходит acquire, но во внутренней транзакции упирается в блокировку строки, которую держит первый, и ждёт. Когда первый закоммитит, второй увидит completed и просто вернёт сохранённый ответ. Двойного списания не будет.
Сохранять ли 500: сравнение со Stripe
Эталоном здесь считается API Stripe. Согласно их документации, Stripe сохраняет статус и тело первого ответа, включая ошибки 500, и возвращает их же на все последующие запросы с этим ключом. Ключи удаляются не раньше чем через 24 часа. Повторное использование ключа с другими параметрами даёт ошибку. Для запросов, не прошедших валидацию или столкнувшихся с параллельным запросом, результат не сохраняется: эндпоинт не начал выполнение, их можно повторять.
Почему Stripe сохраняет даже 500? Потому что внутри у них операция распределена по множеству систем, и при 500 какая-то часть уже могла выполниться. Разрешать повтор опасно.
У нас ситуация другая: списание и сохранение ответа живут в одной транзакции PostgreSQL. При исключении всё откатывается, значит ничего не изменилось и повтор безопасен. Поэтому в блоке except мы освобождаем ключ (locked_at=None).
| Stripe | Наша реализация | |
|---|---|---|
| Область ключа | аккаунт | (user, key) |
| Срок хранения | не менее 24 часов | настраивается, по умолчанию 24 часа |
| Повтор с другими параметрами | ошибка | 422 |
| Параллельный запрос | ошибка конфликта, результат не сохраняется | 409, результат не сохраняется |
| Ошибка валидации | не сохраняется | не сохраняется (400, ключ не захватывается) |
| Ошибка 500 | сохраняется и возвращается | не сохраняется, rollback, повтор разрешён |
По статус-кодам: в IETF есть черновик стандарта заголовка Idempotency-Key (рабочая группа httpapi), и он предлагает похожие коды: 400, если заголовка нет, 409, если запрос ещё выполняется, 422, если ключ используется с другим payload. Заголовок Idempotent-Replayed: true необязателен, но очень помогает при отладке: клиент видит, что ответ повторный.
Если есть внешний платёжный провайдер
Схема выше работает, потому что все изменения в одной базе. В реальном платеже часто есть HTTP-запрос к внешнему провайдеру, и его нельзя положить в транзакцию: если API провайдера отвечает 20 секунд, вы столько же держите блокировки и соединение, а rollback не вернёт деньги, списанные у провайдера.
В этом случае операцию делят на отдельно коммитящиеся шаги (в статье Brandur Leach о Stripe-подобной идемпотентности на Postgres это называется «atomic phases» и «recovery points»):
- В одной транзакции создаётся
Payment(status="pending")с заранее сгенерированным уникальнымprovider_ref. - Вне транзакции вызывается провайдер, ему передаётся этот
provider_ref. Многие провайдеры принимают собственный idempotency key или уникальный ID транзакции на стороне мерчанта. - Получив ответ, в отдельной транзакции переводим
Paymentи idempotency key вcompleted.
Если процесс умер между шагами 2 и 3, запрос, забравший «протухший» ключ, не должен вслепую вызывать провайдера снова. Сначала он проверяет статус платежа по provider_ref и только потом продолжает.
Срок жизни ключа и очистка
Хранить ключи вечно не нужно, но срок должен быть больше самого длинного окна, в котором клиент может повторить запрос. Мобильное приложение может отправить запрос из офлайн-очереди через несколько часов: если ключ удаляется через 10 минут, такой запрос выполнится как новый платёж.
Очистку делаем периодической задачей через Celery beat, батчами, чтобы большой DELETE не держал таблицу:
# payments/tasks.py
from datetime import timedelta
from celery import shared_task
from django.utils import timezone
from .models import IdempotencyKey
RETENTION = timedelta(hours=24)
@shared_task
def purge_idempotency_keys(batch_size: int = 5000) -> int:
cutoff = timezone.now() - RETENTION
total = 0
while True:
ids = list(
IdempotencyKey.objects.filter(created_at__lt=cutoff)
.values_list("pk", flat=True)[:batch_size]
)
if not ids:
return total
deleted, _ = IdempotencyKey.objects.filter(pk__in=ids).delete()
total += deleted
Индекс по created_at нужен именно для этого запроса.
Сторона клиента
Как бы правильно ни был написан сервер, если клиент генерирует новый ключ на каждый retry, всё бесполезно. Правильный клиент выглядит так:
import random
import time
import uuid
import httpx
RETRYABLE = {409, 500, 502, 503, 504}
def pay(order_id: int, amount: int, token: str) -> httpx.Response:
key = str(uuid.uuid4()) # one key per user intent, NOT per attempt
for attempt in range(5):
try:
response = httpx.post(
"https://api.example.com/v1/payments/",
json={"order_id": order_id, "amount": amount},
headers={"Authorization": f"Bearer {token}", "Idempotency-Key": key},
timeout=10,
)
except httpx.TransportError:
pass # timeout, reset connection: the outcome is unknown, retry
else:
if response.status_code not in RETRYABLE:
return response
time.sleep(min(2 ** attempt, 30) + random.random()) # backoff + jitter
raise RuntimeError(f"payment outcome unknown, retry later with key {key}")
Три правила: ключ создаётся вне цикла, 409 и 5xx — сигнал повторить, 4xx (например, 402 или 422) — окончательный ответ. Jitter (random.random()) нужен, чтобы множество клиентов не повторяли запросы синхронно и не роняли сервер повторно.
Подводные камни в продакшене
ATOMIC_REQUESTS = True. Эта настройка оборачивает весь view в одну транзакцию, и захват ключа не коммитится до конца view — другие запросы его не видят. Поэтому стоит@transaction.non_atomic_requests, и этот декоратор должен быть самым внешним.- Область ключа. Если unique constraint только по
key, ключ одного пользователя может совпасть с ключом другого, и в худшем случае чужой сохранённый ответ уйдёт не тому человеку. Всегда(user, key)или(merchant, key). LOCK_TIMEOUTкороче таймаута воркера. Например, таймаут gunicorn 120 секунд, аLOCK_TIMEOUT60 — живой запрос сочтут «протухшим». Внутреннийselect_for_updateзащитит от двойного списания, но не полагайтесь на это, согласуйте таймауты.- Секреты в response body. Сохранённый ответ лежит в базе 24 часа. Номеров карт, токенов и персональных данных там быть не должно.
- Изменчивые поля в хеше. Если клиент добавляет в тело
timestampилиrequest_id, хеш на каждом повторе будет другим, и клиент получит422. В хеш должны входить только поля с бизнес-смыслом, либо установите для клиента правило повторять тело байт в байт. - Повтор после очистки ключа. Повтор, пришедший после удаления ключа, выполнится как новый запрос. Unique constraint на
Payment.order_id— вторая защита именно для этого случая. - Redis недостаточно.
SET key value NX EX 86400хорош для блокировки, но Redis и PostgreSQL не в одной транзакции: деньги списаны, а ответ в Redis не записан, или eviction/failover стёр ключ. Когда речь о деньгах, ключ и результат лучше держать в одной базе. - Celery-задачи тоже могут выполниться дважды. С
acks_lateпри смерти воркера задача выполнится повторно. Та же идея: дайте задаче ID и защитите результат unique constraint'ом.
Чеклист
- Каждый
POST-эндпоинт, двигающий деньги, требуетIdempotency-Key. - Клиент создаёт ключ один раз на намерение и переиспользует его во всех повторах.
- Ключ защищён unique constraint на
(user, key)и захватывается через INSERT, а не проверку. - Хранится канонический хеш запроса; ключ с другим payload получает
422. - Бизнес-изменение и сохранение ответа — в одной транзакции.
- Для выполняющегося запроса —
409, для завершённого — сохранённые статус и тело. - При включённом
ATOMIC_REQUESTSview помеченnon_atomic_requests. - Для «протухших» блокировок есть таймаут, и он больше таймаута воркера.
- Внешнему провайдеру передаётся ваш собственный уникальный reference, при восстановлении сначала проверяется статус.
- Ключи хранятся не меньше 24 часов и удаляются батчами.
Итог
Сеть гарантированно будет терять ответы, поэтому платёжный API обязан переживать повторы. Idempotency key делает это простым: клиент даёт каждому намерению один ключ, сервер захватывает его через unique constraint и сохраняет ответ в одной транзакции с бизнес-изменением. Остальное — детали: хеш, 409/422, срок жизни и recovery для внешних провайдеров. Сделайте их правильно один раз, и вопрос «почему списали дважды» перестанет быть вашей проблемой.
// комментарии
Загружаем комментарии...