← blog · 8 Kasım 2026

Idempotency Anahtarı: Yeniden Denenen POST İsteğini Çift İşlemeden Karşılamak, Kapsam, Eşzamanlılık ve Askıda Kalan Kayıtlar

Zaman aşımına uğrayan bir POST'u yeniden denemek aynı siparişi iki kez yaratabilir. Doğal idempotency, iş verisiyle aynı işlemde saklanan anahtar ve ağ geçidi önbelleği arasında seçim, PostgreSQL ile çalışan bir akış ve bu mekanizmayı sessizce boşa çıkaran tuzaklar.

Ağ bir isteğin sonucunu size her zaman söylemez. İstemci bir ödeme ya da sipariş isteği gönderir, bağlantı zaman aşımına uğrar ve istemci iki ihtimal arasında kalır: istek sunucuya hiç ulaşmadı mı, yoksa işlendi ama cevap yolda mı kayboldu? Yeniden denemezse kullanıcının işi yarım kalabilir, yeniden denerse aynı sipariş iki kez oluşabilir. GET, PUT ve DELETE tanımı gereği tekrarlanabilir işlemlerdir, ama yeni bir kaynak yaratan POST değildir. Idempotency anahtarı bu boşluğu kapatır: istemci her mantıksal işlem için bir anahtar üretir, sunucu aynı anahtarla gelen ikinci isteği yeniden işlemek yerine ilk sonucu döner.

Fikir basit görünür. Asıl iş eşzamanlılık, çökme ve kapsam ayrıntılarındadır.

Üç yaklaşım ve hangisi nerede

Doğal idempotency. İşlemi zaten tekrarlanabilir hâle getirmek her zaman ilk tercihtir. İstemci kaynağın kimliğini kendisi üretir (örneğin bir UUID) ve PUT /orders/{id} ile gönderir ya da iş anahtarı üzerinde benzersiz kısıt vardır (müşterinin sipariş referansı gibi). İkinci istek kısıta çarpar, sunucu var olan kaydı döner. Ek tablo, ek ara katman yoktur ve doğruluğu veritabanı garanti eder. Kaynak yaratan çoğu uç bu biçime sokulabilir.

Sunucuda saklanan anahtar ve cevap. İşlem doğal olarak tekrarlanabilir yapılamıyorsa (dış bir sağlayıcıyı çağıran, birden fazla kayıt yaratan, para taşıyan işlemler) istemci bir Idempotency-Key başlığı gönderir. Sunucu anahtarı, isteğin özetini ve üretilen cevabı kendi veritabanında, iş verisiyle aynı işlemin içinde saklar. Bu, ödeme API'lerinin kullandığı modeldir ve başlık için IETF'te bir taslak standart da bulunur.

Ağ geçidinde önbellek. Bazı ekipler anahtarı API ağ geçidinde ya da Redis gibi ayrı bir depoda tutup cevabı orada önbelleğe alır. Kurulumu kolaydır ama kayıt iş verisiyle aynı işlemde yazılmadığı için tam da önemli olan anlarda yanılır: iş yazıldı, önbelleğe yazılmadan süreç öldü, yeniden deneme işi ikinci kez yapar. Para ve stok gibi tekrarı pahalı işlemlerde bu yaklaşımı kullanmayın.

Taraf tutmak gerekirse: önce doğal idempotency, olmuyorsa iş verisiyle aynı veritabanında saklanan anahtar. Ayrı önbellek ancak tekrarın zararsız olduğu, sadece yükü azaltmak istediğiniz yerde anlamlıdır.

Tablo ve akış

PostgreSQL üzerinde en sade biçim şöyledir:

CREATE TABLE idempotency_keys (
  client_id     bigint      NOT NULL,
  idem_key      text        NOT NULL,
  request_hash  bytea       NOT NULL,
  state         text        NOT NULL DEFAULT 'processing',
  response_code integer,
  response_body jsonb,
  created_at    timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (client_id, idem_key)
);

İstek geldiğinde, iş verisini yazacağınız işlemin içinde önce anahtarı ayırırsınız:

BEGIN;

INSERT INTO idempotency_keys (client_id, idem_key, request_hash)
VALUES ($1, $2, $3)
ON CONFLICT (client_id, idem_key) DO NOTHING
RETURNING idem_key;

Satır dönerse anahtar sizindir: iş kayıtlarını yazın, sonra aynı işlemde cevabı saklayın ve işlemi kapatın.

UPDATE idempotency_keys
   SET state = 'done', response_code = $4, response_body = $5
 WHERE client_id = $1 AND idem_key = $2;

COMMIT;

Satır dönmezse anahtar daha önce kullanılmıştır. Kaydı okuyun, saklanan request_hash gelen isteğinkiyle aynıysa saklı cevabı aynı durum koduyla döndürün; farklıysa isteği reddedin.

Burada PostgreSQL'in sessizce yaptığı bir şey işinize yarar: aynı anahtarla eşzamanlı gelen ikinci INSERT, birinci işlem bitene kadar benzersiz indeks üzerinde bekler. Birinci işlem tamamlanırsa ikinci istek çakışmayı görür ve saklı cevabı döner. Birinci işlem geri alınırsa ikinci istek anahtarı alır ve işi baştan yapar. Her iki sonuç da doğrudur.

Uzun işlemler ve dış çağrılar

Yukarıdaki akış, iş birkaç milisaniye sürdüğünde idealdir. Ödeme sağlayıcısını çağırmak gibi saniyeler süren bir adım varsa bekleyen ikinci istek o süre boyunca bir veritabanı bağlantısını tutar, bağlantı havuzu da kısa sürede tükenir. Bu durumda anahtarı processing durumunda ayrı ve kısa bir işlemle kaydedip hemen kapatın. Aynı anahtarla gelen eşzamanlı istek kaydı processing olarak görür ve beklemek yerine hemen hata alır. IETF taslağı bu durum için 409 Conflict, aynı anahtarın farklı bir gövdeyle yeniden kullanılması için 422 önerir. İstemcinin ne zaman tekrar deneyeceğini bilmesi için Retry-After eklemek iyi olur.

Dış çağrının kendisi de tekrar riskidir. Sizin süreciniz sağlayıcıyı çağırdıktan sonra, sonucu kaydetmeden çökerse bir sonraki deneme sağlayıcıyı yeniden çağırır. Çağırdığınız servis idempotency anahtarı kabul ediyorsa kendi anahtarınızdan türettiğiniz sabit bir anahtarı ona da geçirin; böylece tekrar zinciri her halkada aynı yerde durur. Kabul etmiyorsa işlemi adımlara bölün, her adımın tamamlandığını kayda geçirin ve yeniden denemede önce sağlayıcıya "bu işlem yapıldı mı" diye sorun.

Tuzaklar

İstemci her denemede yeni anahtar üretir. En sık görülen hata budur ve bütün mekanizmayı boşa çıkarır. Anahtar mantıksal işlem başına bir kez, yeniden deneme döngüsünün dışında üretilir ve kalıcı bir yerde saklanır. Mobil istemci uygulama kapanıp açıldığında da aynı anahtarı kullanabilmelidir.

import uuid
import requests

key = str(uuid.uuid4())
for attempt in range(5):
    try:
        r = requests.post(url, json=payload,
                          headers={"Idempotency-Key": key}, timeout=10)
        break
    except requests.exceptions.ConnectionError:
        continue

Anahtarın kapsamı küresel tutulur. Anahtar yalnızca istemci kimliğiyle birlikte anlamlıdır. Kapsamı tüm sistem yaparsanız iki farklı müşteri aynı anahtarı ürettiğinde biri diğerinin saklanan cevabını alır. Bu bir veri sızıntısıdır. Birincil anahtara kimliği doğrulanmış istemciyi, çok kiracılı sistemde kiracıyı mutlaka ekleyin.

Gövde karşılaştırılmaz. Anahtar aynı ama gövde farklıysa istemci ya hata yapıyordur ya da anahtarı yeniden kullanıyordur. Saklı cevabı döndürmek ikinci isteği sessizce yutar. İsteğin özetini saklayın ve uyuşmazlıkta reddedin. Özeti alırken alan sırası ve boşluk farklarının özeti değiştirmemesi için gövdeyi ayrıştırılmış ve normalize edilmiş hâliyle özetleyin.

Geçici hatalar da saklanır. Doğrulama hatası gibi belirlenimci 4xx cevaplarını saklamak doğrudur, aynı istek aynı hatayı almalıdır. Ama zaman aşımı ya da bağımlı servisin düşmesi yüzünden oluşan 5xx cevabını saklarsanız istemci sonsuza kadar aynı hatayı alır. İşlem geri alındıysa anahtar kaydı da geri alınır ve bu sorun kendiliğinden çözülür; anahtarı ayrı işlemde kaydettiğiniz durumda ise geçici hatada kaydı açıkça silin.

Askıda kalan processing kayıtları. Süreç anahtarı ayırdıktan sonra çökerse kayıt processing hâlinde kalır ve istemci sonsuza kadar 409 alır. Kayda bir kilit zamanı koyun ve belli bir süreden sonra kurtarma işine devredin. Kurtarma "kaydı sil, baştan yap" değildir: yan etki gerçekleşmiş olabilir, önce hangi adıma kadar gelindiğine bakılır.

Saklama süresi yeniden deneme penceresinden kısadır. Anahtarları sonsuza kadar tutmak gerekmez, ama istemcilerin ve aradaki kuyrukların en uzun yeniden deneme süresinden daha uzun tutmak gerekir. Ödeme API'lerinde genelde 24 saat tercih edilir. Temizliği tek büyük DELETE ile değil, küçük partilerle yapın; aksi hâlde tabloyu kilitleyen ve çok sayıda ölü satır üreten bir iş elde edersiniz.

Saklı cevap eskir. Saklı cevap, işlemin o anki sonucudur. Kaynak sonradan değiştiyse yeniden deneme eski hâli görür. Bu bir hata değil, idempotency'nin anlamıdır; ama istemci belgelerinde açıkça yazılmalıdır.

Ne zaman gerekmez

İşlem zaten doğal olarak tekrarlanabiliyorsa ek katman sadece bakım yükü getirir. Kaynak kimliğini istemcinin ürettiği bir PUT ya da iş anahtarı üzerinde benzersiz kısıt çoğu zaman yeterlidir. Tekrarın zararsız olduğu işlemlerde de (bir sayacı yeniden hesaplamak, bir önbelleği tazelemek) bu mekanizmaya gerek yoktur. Idempotency anahtarı, tekrarın gerçek bir maliyeti olduğu ve işlemin başka bir yolla tekrarlanabilir yapılamadığı yerler içindir. Orada da iş verisiyle aynı işlemde, istemci kapsamında ve gövde karşılaştırmasıyla yapılmazsa güvence verdiği izlenimini verir ama vermez.