Все заметки
Финтех

Ключи идемпотентности: как не списать деньги дважды, когда клиент повторяет запрос

Ответ потерялся, клиент повторил запрос, и деньги списались дважды. Разбираем 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 — кто-то успел раньше.

Отсюда обработка запроса в три шага:

  1. Захват ключа. Вставляем строку со статусом started в отдельной короткой транзакции и сразу коммитим. Остальные запросы тут же видят, что ключ занят.
  2. Выполнение работы. Списание денег и запись ответа в ключ — в одной транзакции. Сохраняется либо всё, либо ничего.
  3. Ответ на повтор. Ключ 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»):

  1. В одной транзакции создаётся Payment(status="pending") с заранее сгенерированным уникальным provider_ref.
  2. Вне транзакции вызывается провайдер, ему передаётся этот provider_ref. Многие провайдеры принимают собственный idempotency key или уникальный ID транзакции на стороне мерчанта.
  3. Получив ответ, в отдельной транзакции переводим 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_TIMEOUT 60 — живой запрос сочтут «протухшим». Внутренний 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_REQUESTS view помечен non_atomic_requests.
  • Для «протухших» блокировок есть таймаут, и он больше таймаута воркера.
  • Внешнему провайдеру передаётся ваш собственный уникальный reference, при восстановлении сначала проверяется статус.
  • Ключи хранятся не меньше 24 часов и удаляются батчами.

Итог

Сеть гарантированно будет терять ответы, поэтому платёжный API обязан переживать повторы. Idempotency key делает это простым: клиент даёт каждому намерению один ключ, сервер захватывает его через unique constraint и сохраняет ответ в одной транзакции с бизнес-изменением. Остальное — детали: хеш, 409/422, срок жизни и recovery для внешних провайдеров. Сделайте их правильно один раз, и вопрос «почему списали дважды» перестанет быть вашей проблемой.

// комментарии

Загружаем комментарии...

    // следующий шаг

    Давайте построим что-нибудь вместе.

    Написать в Telegram
    aslbek@asldev: ~
    ❯