API, Entegrasyon ve Kurumsal Sistemler
API Entegrasyonlarında Idempotency ve Hata Yönetimi Nasıl Kurulur
Tekrarlanan API istekleri, zaman aşımı ve kısmi başarısızlıklar veri tutarsızlığı yaratabilir. Idempotency tasarımı, retry politikaları ve güvenli hata yönetimiyle bunu nasıl önleyeceğinizi anlatıyoruz.
Yayınlandı: 4 Ağustos 2026 · Güncellendi: 4 Ağustos 2026
API entegrasyonlarında idempotency nedir?
API entegrasyonlarında idempotency, aynı isteğin birden fazla kez gönderilmesi durumunda sistemin nihai sonucunun değişmemesi anlamına gelir. Bu yaklaşım, özellikle ödeme, sipariş, stok ve müşteri kaydı gibi işlerde veri tutarlılığını korumak için kritik hale gelir. Ağ kesintisi, zaman aşımı ya da istemci tarafında yeniden gönderim olduğunda aynı işlemin yanlışlıkla tekrar çalışması ciddi operasyonel sorunlar doğurabilir.
Pratikte amaç, tekrar eden isteği tamamen engellemekten çok, onu güvenli biçimde tanımak ve ikinci kez işleme sokmamaktır. Bunun için idempotency key, işlem durumu takibi ve işlem sonucunu saklama gibi yöntemler kullanılır. Böylece sistem, aynı isteği yeniden aldığında yeni bir kayıt üretmek yerine önceki sonucu döndürür veya işleme başlamadan durur. Bu konu, güvenilir API tasarımının temel taşlarından biridir.
Kaynakların önerdiği yaklaşım, yalnızca HTTP metoduna güvenmek yerine iş süreci mantığına da idempotency eklemektir. Özellikle entegrasyonlar farklı servisler, kuyruklar ve ara katmanlar içeriyorsa, tek bir katmandaki kontrol yeterli olmaz. Bu nedenle API gateway, uygulama servisi ve veritabanı seviyesinde tutarlı bir tasarım gerekir. Daha geniş mimari için [API entegrasyonu hizmeti](/api-ve-sistem-entegrasyonlari) ve [özel yazılım geliştirme](/ozel-yazilim-gelistirme) yaklaşımları bu tür akışlarda değerlidir.
Öne çıkanlar
İdempotent tasarımda öne çıkan yapı taşları
Güvenilir entegrasyon kurmak için yalnızca tekrar denemeyi açmak yeterli değildir. İstek kimliği üretimi, tekrar deneme sınırları, hata sınıflandırması ve işlem durumunun saklanması birlikte düşünülmelidir. Aksi halde istemci tarafında yapılan her retry, arka tarafta yeni bir işlem gibi algılanabilir. Bu da ödeme çift çekimi, mükerrer sipariş ya da yinelenen müşteri kaydı gibi hatalara yol açar. En sağlıklı yaklaşım, her işleme benzersiz bir işlem anahtarı eklemek ve bu anahtarı kısa süreli bir işlem hafızasında ya da kalıcı kayıtta kontrol etmektir. Sunucu daha önce aynı anahtarı gördüyse, yeni bir iş akışı başlatmak yerine önceki yanıtı döndürmelidir. Bu mantık, entegrasyon izleme ve hata yönetimiyle birlikte kurulduğunda çok daha güvenilir hale gelir. Özellikle dış sistemlerle çalışan projelerde, hata mesajlarının teknik ekip kadar iş kullanıcıları için de anlaşılır olması önemlidir. Hata sınıfını doğru ayırmak; geçici ağ hatası, doğrulama hatası, bağımlı servis hatası ve iş kuralı ihlali gibi durumlar için farklı davranış tanımlamayı kolaylaştırır. Böylece aynı retry davranışı her hata tipine körlemesine uygulanmaz.
Benzersiz işlem anahtarı
Her isteği aynı işlemi temsil eden tekil bir anahtarla etiketleyin.
İşlem durumu kaydı
Başladı, işlendi, tamamlandı, başarısız gibi durumları ayrı ayrı saklayın.
Hata sınıflandırması
Geçici ve kalıcı hataları aynı sepete koymayın; retry kararını buna göre verin.
Uygulama süreci
Sağlam retry akışı nasıl kurgulanır?
Retry politikası, başarısız her isteği otomatik olarak tekrar göndermek değildir. Doğru tasarım, hangi hataların yeniden denenebileceğini, kaç kez deneneceğini ve denemeler arasında nasıl beklenileceğini belirler. Özellikle geçici ağ kesintileri, gateway zaman aşımı veya bağımlı servislerin kısa süreli erişilemezliği gibi durumlar retry için uygundur. Buna karşılık doğrulama hatası ya da yetkisiz erişim gibi durumlarda yeniden deneme anlamlı değildir. Exponential backoff yaklaşımı, denemeler arasındaki bekleme süresini kademeli olarak artırır. Bu sayede hem hedef servisin yükü azaltılır hem de zincirleme hata üretme riski düşer. Kuyruk tabanlı mimarilerde bunu dead-letter yaklaşımıyla desteklemek, sürekli başarısız olan mesajların ana akışı tıkamasını önler. Bir mesaj belirlenen deneme sınırını aşarsa ayrı bir kuyruğa alınarak manuel incelemeye yönlendirilebilir. Bu akışın sağlıklı çalışması için istemci, ara servis ve hedef API birbirine aynı dili konuşmalıdır. İstemci retry ederken aynı idempotency key'i göndermeli, hedef servis de bu anahtarı işleyip önceki sonucu tanımalıdır. Böylece yeniden deneme güvenli bir dayanıklılık mekanizmasına dönüşür, rastgele tekrar davranışına değil. Daha kapsamlı operasyonel destek için [BT bakım ve teknik destek hizmetleri](/bt-bakim-ve-teknik-destek-hizmetleri) ve [bulut altyapı ve buluta geçiş hizmetleri](/bulut-altyapi-ve-buluta-gecis-hizmetleri) de önemli bir dayanak sağlar.
- 01
Hata tespiti
Önce hatanın geçici mi kalıcı mı olduğunu ayırın, sonra retry kararı verin.
- 02
Kademeli bekleme
Deneme aralıklarını sabit tutmak yerine aşamalı artırın.
- 03
Dead-letter ayrıştırma
Sürekli başarısız mesajları ana akıştan ayırın ve incelemeye alın.
Karşılaştırma
HTTP metodu ile gerçek idempotency arasındaki fark
Protokol seviyesi güven verir gibi görünür
Ama uygulama katmanı yine risk taşıyabilir
Tekrarlar güvenli biçimde tanınır
Aynı işin ikinci kez etkisi engellenir
Sorumluluk tek tarafa kayar gibi görünür
Dış referans ve sorgu ile dengelenir
Kontrol listesi
Güvenilir entegrasyon için uygulama kontrol listesi
İdempotency ve hata yönetimini birlikte tasarlamak, entegrasyonun en başında ele alınmalıdır. Sonradan eklenen önlemler çoğu zaman parçalı kalır ve operasyon tarafında yeni karmaşıklık üretir. Aşağıdaki kontrol listesi, ödeme, sipariş ve müşteri akışlarında temel güvenlik çizgisini kurmak için kullanılabilir. Benzer yapıları [e-ticaret yazılımı geliştirme](/e-ticaret-yazilimi-gelistirme) ve [özel CRM yazılımı geliştirme](/ozel-crm-yazilimi-gelistirme) projelerinde de uygulamak gerekir. Kontrol listesi, teknik ekipler kadar iş analistleri ve operasyon sorumluları için de faydalıdır. Çünkü retry sınırları, dead-letter akışı, durum sorgusu ve kullanıcı bildirimi birbirine bağlıdır. Bir halka eksik kalırsa sistem yine aynı isteği yanlış yorumlayabilir. Bu nedenle tasarım, test ve devreye alma aşamaları birlikte yürütülmelidir. Kullanıcıya gösterilen hata mesajları da teknik ayrıntıdan çok aksiyon bilgisi içermelidir. Aşağıdaki maddeler, entegrasyonun üretimde sürpriz üretmesini engellemek için pratik bir başlangıç sunar. Her bir maddeyi ilgili servis, kuyruk ve veri modeli üzerinde ayrı ayrı doğrulamak gerekir. Özellikle dış sistem bağımlılığı yüksek projelerde, gözleme ve kayıt yapısına yatırım yapmak büyük fark yaratır. İleri seviye kurulumlar için [API entegrasyonu ile sistemlerinizi güvenle bağlayın](/api-ve-sistem-entegrasyonlari) hizmeti uygun bir başlangıç noktasıdır.
- ✓
Her işlem için benzersiz anahtar üretin
İstek tekrarını ayıracak bir idempotency key belirleyin.
- ✓
Retry politikasını hata tipine göre ayırın
Geçici hatalar için retry, kalıcı hatalar için durdurma tanımlayın.
- ✓
İşlem durumunu saklayın
İşlendi, beklemede, başarısız, tamamlandı gibi durumları izleyin.
- ✓
Dead-letter akışını planlayın
Sürekli başarısız mesajları ayrı bir kanala yönlendirin.
- ✓
Kullanıcıya güvenli mesaj verin
Teknik hata kodunu değil, aksiyon aldıran kısa bir durum bilgisi gösterin.
Hata yönetiminde güvenli bildirim neden önemlidir?
Entegrasyon hatalarında hedef yalnızca sistemi çalışır tutmak değildir; kullanıcı deneyimini de kontrollü tutmaktır. Kullanıcıya doğrudan teknik izler, stack trace ya da belirsiz bir başarısızlık sunmak yerine, işlemin durumu hakkında net ama güvenli bir açıklama verilmelidir. Bu, hem tekrar deneme davranışını daha anlamlı kılar hem de destek sürecini sadeleştirir.
Güvenli bildirim yaklaşımı, hata detayını tamamen gizlemek değil, doğru kişiye doğru seviyede iletmektir. Son kullanıcıya sade bir durum mesajı, teknik ekibe ise kayıt numarası, zaman damgası ve işlem anahtarı gibi bilgiler gerekir. Böylece hata ayıklama süreci hızlanır ve aynı sorun tekrar yaşandığında geçmiş kayıtlarla ilişkilendirme yapılabilir. İzleme ve loglama, bu noktada en az idempotency kadar önemlidir.
Uzun vadede en iyi sonuç, idempotent istek tasarımı ile sistematik hata yönetiminin birlikte uygulanmasıdır. Bir taraf yalnızca tekrarları, diğer taraf yalnızca hataları düşünürse mimari eksik kalır. Oysa her iki konu birlikte ele alındığında kurumsal entegrasyonlar daha öngörülebilir hale gelir. Bu da [bulut altyapı ve buluta geçiş hizmetleri](/bulut-altyapi-ve-buluta-gecis-hizmetleri) ile desteklenen daha dayanıklı bir operasyon modeli oluşturur.
Keşfetmeye devam et
İlgili içerik ve hizmetler
Konuyu tamamlayan Bikare içeriklerine göz atın.
