Bir API entegrasyonu ilk testlerde sorunsuz çalışabilir; ancak gerçek kullanım başladığında zaman aşımı, hız sınırı, bağlantı kopması, geçersiz veri, tekrar eden istek ve kısmi işlem gibi durumlarla karşılaşır. Sorun, bir isteğin hata vermesi değil; sistemin bu hatanın nedenini anlayamaması, işlemi güvenli biçimde tekrar edememesi ve kayıp kayıtları sonradan bulamamasıdır.
Sağlam bir entegrasyon, yalnızca iki sistemi birbirine bağlamaz. Hangi hatanın yeniden deneneceğini, hangi işlemin durdurulacağını, aynı isteğin iki kez gelmesi durumunda ne olacağını ve operasyon ekibinin arızayı nasıl izleyeceğini önceden tanımlar. Bu rehber, API entegrasyonu planlayan işletmeler ve özel yazılım ekipleri için uygulanabilir bir hata yönetimi çerçevesi sunar.
API entegrasyonunda hata yönetimi neyi kapsar?
Hata yönetimi; hatayı yakalamak, sınıflandırmak, uygun tepkiyi vermek, işlemin durumunu korumak ve gerekli kişilere görünür hâle getirmek anlamına gelir. Her hata aynı değildir. Geçici ağ kesintisi birkaç saniye sonra düzelebilirken geçersiz vergi numarası veya yetkisiz erişim kendiliğinden çözülmez.
İzleme ise yalnızca hata logu tutmak değildir. Bir isteğin hangi sistemden çıktığını, hangi adımlardan geçtiğini, kaç kez denendiğini, nerede geciktiğini ve iş sonucunun oluşup oluşmadığını gösterebilmelidir. Teknik hata ile iş hatasının ayrılması da önemlidir. HTTP bağlantısı başarılı olsa bile karşı sistem “sipariş reddedildi” yanıtı verebilir.
Temel ilke: Entegrasyonun başarısı yalnızca “200 OK” yanıtıyla ölçülmemelidir. Asıl soru, iş kaydının hedef sistemde doğru ve yalnızca bir kez oluşup oluşmadığıdır.
Hataları geçici, kalıcı ve belirsiz olarak sınıflandırın
Doğru tepkiyi verebilmek için ilk adım hata türünü belirlemektir. Her hatayı otomatik olarak tekrar denemek, hizmet kesintisini büyütebilir veya aynı işlemin birden fazla kez oluşmasına yol açabilir.
| Hata türü | Örnek | Önerilen tepki | Risk |
|---|---|---|---|
| Geçici hata | Zaman aşımı, kısa süreli ağ kesintisi, 429 hız sınırı, bazı 5xx yanıtları | Sınırlı sayıda, gecikmeli ve rastgeleleştirilmiş yeniden deneme | Kontrolsüz retry trafiği hizmeti daha fazla zorlayabilir |
| Kalıcı teknik hata | Geçersiz kimlik bilgisi, bulunmayan uç nokta, uyumsuz API sürümü | İşlemi durdurma, alarm üretme ve yapılandırmayı düzeltme | Sürekli yeniden deneme gereksiz trafik ve maliyet oluşturur |
| İş kuralı hatası | Eksik adres, kapalı cari hesap, stok yetersizliği | Kullanıcı veya operasyon ekibine açıklanabilir hata sunma | Teknik hata gibi ele alınırsa sorun gizlenir |
| Belirsiz sonuç | İstek gönderildi fakat yanıt gelmeden bağlantı koptu | Durum sorgulama veya idempotency anahtarıyla güvenli doğrulama | Körlemesine tekrar deneme çift kayıt oluşturabilir |
Belirsiz sonuç en kritik kategorilerden biridir. Örneğin ödeme veya sipariş oluşturma isteği hedef sistemde tamamlanmış olabilir; ancak yanıt istemciye ulaşmamış olabilir. Sistem bu durumu doğrudan “başarısız” sayıp aynı isteği tekrar gönderirse mükerrer kayıt oluşturabilir.
Timeout değerlerini açıkça tanımlayın
Bir API çağrısının sonsuza kadar beklemesine izin verilmemelidir. Bağlantı kurma, yanıt bekleme ve toplam işlem süresi için uygun timeout değerleri tanımlanmalıdır. Aksi hâlde yavaşlayan bir dış servis, uygulamadaki iş parçacıklarını veya bağlantı havuzunu tüketerek zincirleme yavaşlamaya neden olabilir.
Timeout değeri çok kısa seçilirse normal çalışan istekler gereksiz yere kesilir; çok uzun seçilirse arızanın etkisi büyür. Değerler, entegrasyonun gerçek yanıt süreleri ve işin kabul edilebilir bekleme süresi ölçülerek belirlenmelidir. Kullanıcı ekranda beklemek zorunda değilse işlem kuyruğa alınabilir ve arka planda tamamlanabilir.
Timeout oluştuğunda işlemin hedef sistemde gerçekleşip gerçekleşmediği her zaman bilinmez. Bu nedenle özellikle yazma işlemlerinde durum sorgulama uç noktası, dış referans numarası veya idempotency anahtarı kullanılmalıdır.
Retry yalnızca geçici ve güvenli hatalarda uygulanmalıdır
Yeniden deneme mekanizması, kısa süreli arızalarda işlemin otomatik olarak tamamlanmasını sağlayabilir. Ancak sabit aralıklarla ve sınırsız tekrar yapmak doğru değildir. Çok sayıda istemci aynı anda tekrar denediğinde “retry storm” oluşabilir ve zaten zorlanan servis daha fazla yük altında kalabilir.
AWS, geçici hatalarda yeniden deneme aralıklarının giderek uzatıldığı exponential backoff yaklaşımını ve istemcilerin aynı anda tekrar denemesini azaltmak için jitter eklenmesini önerir. Maksimum deneme sayısı da sınırlandırılmalıdır AWS Prescriptive Guidance. Azure’ın geçici hata rehberi de sonsuz yeniden deneme kullanılmamasını ve servis iyileşmesine fırsat veren sınırlı politikalar tanımlanmasını vurgular Azure Architecture Center.
Bir retry politikası en az şu kararları içermelidir:
- Hangi hata kodları ve istisnalar yeniden denenecek?
- İlk bekleme süresi ne olacak?
- Bekleme süresi hangi oranda artacak?
- Jitter nasıl uygulanacak?
- Maksimum deneme sayısı ve toplam süre ne olacak?
- Denemeler tükendiğinde işlem nereye taşınacak?
- İşlem tekrar edildiğinde çift kayıt nasıl önlenecek?
400 sınıfındaki tüm yanıtlar aynı şekilde yorumlanmamalıdır. 429 hız sınırı çoğu durumda geçici olabilirken 401 yetkisiz erişim veya 422 geçersiz veri genellikle yapılandırma ya da veri düzeltmesi gerektirir. Karşı API’nin dokümantasyonu ve döndürdüğü özel hata gövdesi dikkate alınmalıdır.
Idempotency çift kayıt riskini azaltır
Idempotent işlem, aynı isteğin tekrar gönderilmesi durumunda iş sonucunun birden fazla kez oluşmasını önler. Özellikle sipariş, ödeme, fatura, rezervasyon ve stok hareketi gibi yazma işlemlerinde kritik öneme sahiptir.
İstemci her mantıksal işlem için benzersiz bir idempotency anahtarı üretebilir. Hedef sistem bu anahtarla daha önce tamamlanan isteği tanır ve yeni kayıt oluşturmak yerine önceki sonucu döndürür. AWS dokümantasyonu, idempotent isteğin başarılı ilk işlemden sonraki tekrarların yeni bir değişiklik oluşturmamasını sağladığını açıklar AWS Documentation.
Idempotency yalnızca HTTP başlığı eklemek değildir. Anahtarın hangi iş işlemini temsil ettiği, ne kadar süre saklanacağı, aynı anahtarla farklı içerik gönderildiğinde ne yapılacağı ve eş zamanlı isteklerin nasıl kilitleneceği tanımlanmalıdır. Hedef API idempotency desteklemiyorsa gönderen sistem kendi dış referansını kullanmalı ve tekrar öncesinde hedefte kayıt sorgulaması yapmalıdır.
Circuit breaker sürekli başarısız çağrıları geçici olarak durdurur
Bir dış servis uzun süre erişilemez olduğunda her yeni isteğin aynı servise gönderilmesi kaynak tüketir ve kullanıcı bekleme süresini artırır. Circuit breaker, hata oranı belirli eşiği aştığında çağrıları geçici olarak durdurur. Bekleme süresi sonunda sınırlı deneme yaparak servisin iyileşip iyileşmediğini kontrol eder.
Azure Architecture Center, retry ile circuit breaker’ın farklı amaçlara sahip olduğunu belirtir. Retry geçici hatanın düzeleceğini varsayarak işlemi tekrarlar; circuit breaker ise başarısız olma ihtimali yüksek çağrıları bir süre engelleyerek sistemin toparlanmasına yardım eder Azure Architecture Center.
Circuit breaker devredeyken uygulama her zaman tamamen kullanılamaz olmak zorunda değildir. Örneğin muhasebe servisi kapalıysa sipariş yerel sistemde “aktarılmayı bekliyor” durumuna alınabilir. Kullanıcı işlemini tamamlar, entegrasyon daha sonra güvenli biçimde devam eder. Bu yaklaşım graceful degradation olarak değerlendirilir.
Senkron çağrı yerine kuyruk ne zaman kullanılmalıdır?
İşlemin anında tamamlanması gerekmiyorsa kuyruk tabanlı entegrasyon daha dayanıklı olabilir. Ana uygulama iş olayını kuyruğa yazar; ayrı çalışan entegrasyon işçisi hedef API’ye gönderir. Böylece dış servisin yavaşlığı kullanıcı işlemini doğrudan engellemez.
Kuyruk kullanımı özellikle şu durumlarda uygundur:
- Toplu veri aktarımı yapılıyorsa
- Karşı servis sık sık hız sınırı uyguluyorsa
- İşlem birkaç saniye veya dakika gecikebiliyorsa
- Yük dalgalıysa ve işçiler bağımsız ölçeklenmek isteniyorsa
- Başarısız kayıtların daha sonra yeniden işlenmesi gerekiyorsa
Kuyruk sistemleri çoğunlukla “en az bir kez teslim” davranışı gösterebilir. Bu nedenle aynı mesajın tekrar gelmesi mümkün kabul edilmeli ve işleyici idempotent tasarlanmalıdır. Mesaj başarıyla işlendiği onaylanmadan kuyruktan silinmemelidir.
Kalıcı hataları dead-letter queue ile ayırın
Belirlenen deneme sayısını aşan mesajların ana kuyrukta sonsuza kadar dönmesi diğer işlemleri geciktirebilir. Dead-letter queue veya hata kuyruğu, işlenemeyen mesajları ayrı bir alana taşır. Böylece normal akış devam ederken problemli kayıtlar incelenebilir.
Google Cloud Eventarc dokümantasyonu, kalıcı teslim hatalarının dead-letter topic üzerinde saklanıp analiz edilebileceğini; en az bir kez teslim nedeniyle işleyicilerin tekrarlanan olaylara karşı idempotent tasarlanması gerektiğini belirtir Google Cloud Documentation.
Hata kuyruğundaki kayıt için yalnızca ham mesaj saklamak yeterli değildir. Şunlar da görünür olmalıdır:
- İşlem ve korelasyon kimliği
- Kaynak ve hedef sistem
- İlk ve son deneme zamanı
- Deneme sayısı
- Son hata kodu ve açıklaması
- İş kaydının dış referansı
- Yeniden işleme durumu
- Sorumlu ekip veya kullanıcı
Operasyon ekibi hatalı kaydı düzelttikten sonra kontrollü biçimde yeniden kuyruğa alabilmelidir. Bu akış, talep ve destek sistemi ile ilişkilendirilirse teknik hata, iş takibine dönüştürülebilir.
Korelasyon kimliği ile uçtan uca takip kurun
Bir sipariş işlemi web uygulamasından başlayıp ödeme, stok, kargo ve muhasebe servislerinden geçebilir. Her sistem farklı log üretirse tek bir işlemin izini sürmek zorlaşır. Korelasyon kimliği, aynı iş akışına ait kayıtları sistemler arasında ilişkilendirir.
İlk sistem benzersiz bir correlation ID veya trace ID üretir ve sonraki API çağrılarına taşır. Her log kaydı; bu kimliğin yanında entegrasyon adı, işlem türü, süre, deneme sayısı ve sonuç durumunu içermelidir. Kişisel veriler, erişim belirteçleri, parolalar veya tam kart bilgileri loglara yazılmamalıdır.
OpenTelemetry, izleri bir isteğin sistem içindeki yolunu; metrikleri çalışma anındaki ölçümleri; logları ise olay kayıtlarını temsil eden gözlemlenebilirlik sinyalleri olarak tanımlar OpenTelemetry Documentation. Trace ID ve span ID ile logların dağıtık izlerle ilişkilendirilmesi, hatanın hangi adımda oluştuğunu bulmayı kolaylaştırır.
Hangi metrikler izlenmelidir?
Yalnızca toplam hata sayısını izlemek yeterli değildir. Trafik arttığında hata sayısı artsa bile hata oranı değişmemiş olabilir. Teknik metriklerin yanında iş sonucu metrikleri de bulunmalıdır.
| Metrik grubu | Örnek göstergeler | Yanıtladığı soru |
|---|---|---|
| Trafik | İstek sayısı, mesaj sayısı, veri hacmi | Entegrasyon ne kadar yük taşıyor? |
| Başarı | Başarı oranı, işlenen kayıt, reddedilen iş kaydı | Teknik çağrı değil, iş sonucu oluşuyor mu? |
| Gecikme | Yanıt süresi, kuyruk bekleme süresi, uçtan uca tamamlama süresi | Kayıt hedef sisteme ne kadar sürede ulaşıyor? |
| Hata | Timeout, 4xx, 5xx, iş kuralı hatası, retry sayısı | Hata hangi türde ve nerede yoğunlaşıyor? |
| Kapasite | Kuyruk uzunluğu, aktif işçi, hız sınırı kullanımı | Sistem yükü karşılayabiliyor mu? |
| Tutarlılık | Eksik kayıt, mükerrer kayıt, mutabakat farkı | Kaynak ve hedef sistem aynı iş gerçeğini taşıyor mu? |
Alarm eşikleri iş etkisine göre belirlenmelidir. Tek bir başarısız kayıt her zaman gece alarmı gerektirmeyebilir; fakat ödeme entegrasyonunda belirli süre boyunca hiç başarılı işlem olmaması kritik olabilir. Alarmın içinde entegrasyon adı, hata türü, etkilenen işlem sayısı ve inceleme bağlantısı yer almalıdır.
Mutabakat işlemi görünmeyen hataları bulur
Bazı entegrasyon hataları teknik olarak görünmez. Kaynak sistem isteği başarılı sayabilir, fakat hedefte kayıt eksik veya farklı tutarda oluşmuş olabilir. Periyodik mutabakat, iki sistemdeki kayıtları iş anahtarları üzerinden karşılaştırır.
Örneğin gün sonunda kaynak sistemdeki fatura numaraları ile muhasebe sistemindeki kayıtlar karşılaştırılabilir. Eksik, mükerrer veya tutarı farklı kayıtlar raporlanır. Mutabakat, gerçek zamanlı hata yönetiminin yerine geçmez; kaçan sorunları yakalayan ikinci kontrol katmanıdır.
Özellikle finansal, stok veya rezervasyon verilerinde yalnızca loglara güvenmek yerine iş düzeyinde doğrulama yapılmalıdır. özel yazılım geliştirilirken mutabakat ekranı ve yeniden işleme yetkileri gereksinim dokümanına baştan eklenmelidir.
Gerçekçi bir entegrasyon senaryosu
Varsayımsal olarak bir e-ticaret sistemindeki siparişlerin ön muhasebe yazılımına aktarıldığını düşünelim. Sipariş tamamlandığında entegrasyon olayı kuyruğa yazılır. Her olay sipariş numarası, işleme ait benzersiz idempotency anahtarı ve korelasyon kimliği taşır.
Entegrasyon işçisi muhasebe API’sine belirlenmiş timeout ile çağrı yapar. 429 veya geçici 5xx yanıtında exponential backoff ve jitter ile sınırlı retry uygular. 401 yanıtında tekrar denemek yerine kimlik bilgisi alarmı üretir. Geçersiz vergi bilgisi gibi iş hatasında sipariş “müdahale gerekli” durumuna alınır.
Denemeler tükendiğinde kayıt hata kuyruğuna taşınır. Operasyon ekranında sipariş numarası, hata açıklaması, deneme sayısı ve son yanıt görüntülenir. Veri düzeltildikten sonra yetkili kullanıcı kaydı yeniden işler. Gün sonu mutabakatı, e-ticaret ve muhasebe sistemindeki sipariş toplamlarını karşılaştırarak görünmeyen eksikleri raporlar.
API entegrasyonu hata yönetimi kontrol listesi
- Geçici, kalıcı, iş kuralı ve belirsiz sonuç hataları ayrılıyor mu?
- Her dış çağrı için bağlantı ve toplam timeout tanımlı mı?
- Retry yalnızca uygun hata türlerinde ve sınırlı sayıda mı uygulanıyor?
- Exponential backoff ve jitter kullanılıyor mu?
- Yazma işlemlerinde idempotency veya güvenilir dış referans var mı?
- Uzun süreli arızalarda circuit breaker devreye giriyor mu?
- Gecikebilen işlemler kuyruk üzerinden ayrıştırılıyor mu?
- Kalıcı hatalar ayrı hata kuyruğunda tutuluyor mu?
- İşlem uçtan uca korelasyon kimliğiyle izlenebiliyor mu?
- Loglarda hassas bilgiler maskeleniyor mu?
- Teknik metriklerin yanında iş sonucu metrikleri izleniyor mu?
- Kaynak ve hedef sistem arasında periyodik mutabakat yapılıyor mu?
- Hatalı kayıtlar yetkili kullanıcı tarafından güvenli biçimde yeniden işlenebiliyor mu?
Sonuç: Hatasız entegrasyon değil, kontrollü hata hedeflenmelidir
Hiç hata vermeyen bir dış servis veya ağ bağlantısı varsayımı gerçekçi değildir. Dayanıklı entegrasyonun amacı hatayı tamamen ortadan kaldırmak değil; hatanın etkisini sınırlamak, kaydı kaybetmemek, çift işlem üretmemek ve sorunu hızlı biçimde görünür hâle getirmektir.
Timeout, sınırlı retry, idempotency, circuit breaker, kuyruk, dead-letter akışı, korelasyon kimliği ve mutabakat birlikte çalıştığında entegrasyon operasyonel olarak yönetilebilir hâle gelir. Bu yapı kurulmadan yalnızca başarılı demo akışına bakılarak canlıya çıkmak, gerçek yükte veri kaybı ve manuel düzeltme maliyeti doğurabilir.
Sıkça Sorulan Sorular
API isteği hata verdiğinde her zaman yeniden denenmeli mi?
Hayır. Yeniden deneme yalnızca geçici olma ihtimali bulunan ve güvenli biçimde tekrar edilebilen hatalarda uygulanmalıdır. Zaman aşımı, kısa süreli bağlantı problemi, 429 hız sınırı ve bazı 5xx yanıtları retry adayı olabilir. Geçersiz veri, yanlış kimlik bilgisi veya bulunmayan uç nokta gibi kalıcı hatalar kendiliğinden düzelmez. Ayrıca yazma işlemi hedefte tamamlanmış fakat yanıt kaybolmuş olabilir. Bu durumda körlemesine retry yerine idempotency anahtarı veya durum sorgulama mekanizması kullanılmalıdır.
Exponential backoff ve jitter neden birlikte kullanılır?
Exponential backoff, her başarısız denemeden sonra bekleme süresini artırarak arızalı servise gönderilen yükü azaltır. Jitter ise bu bekleme süresine rastgelelik ekler. Çok sayıda istemci aynı anda hata aldığında yalnızca backoff kullanılırsa hepsi benzer anda yeniden deneyebilir. Jitter, bu istekleri zamana yayarak yeni bir trafik dalgası oluşma riskini düşürür. Politika yine de maksimum deneme sayısı ve toplam süreyle sınırlandırılmalıdır. Retry mekanizması, kalıcı hataları gizleyecek veya sonsuza kadar çalışacak biçimde tasarlanmamalıdır.
Idempotency anahtarı ne kadar süre saklanmalıdır?
Süre, işlemin tekrar gelebileceği pencereye ve iş riskine göre belirlenir. Ödeme, sipariş veya rezervasyon gibi kritik işlemlerde istemcinin timeout sonrası saatler sonra bile tekrar deneyebileceği düşünülmelidir. Anahtar çok kısa saklanırsa eski bir tekrar yeni işlem gibi kabul edilebilir; gereksiz uzun saklanırsa depolama ve yönetim yükü artar. Aynı anahtarla farklı içerik gönderilmesi reddedilmeli veya açık hata üretmelidir. Saklama politikası, işlem türü ve karşı sistemin tekrar davranışıyla birlikte dokümante edilmelidir.
Circuit breaker ile retry arasındaki fark nedir?
Retry, geçici bir hatanın kısa süre içinde düzeleceği beklentisiyle işlemi sınırlı sayıda tekrarlar. Circuit breaker ise hata oranı yükseldiğinde başarısız olma ihtimali yüksek yeni çağrıları geçici olarak durdurur. Böylece hem uygulamanın kaynakları korunur hem de dış servise toparlanma fırsatı verilir. Belirli bekleme süresinden sonra az sayıda test çağrısı yapılır; servis iyileşmişse devre yeniden kapanır. İki desen birlikte kullanılabilir, ancak yanlış yapılandırılırsa retry mekanizması circuit breaker açılmadan önce gereksiz trafik oluşturabilir.
Dead-letter queue içindeki kayıtlar otomatik olarak tekrar işlenmeli mi?
Her kayıt otomatik olarak tekrar işlenmemelidir. Hata kuyruğuna düşen mesajlar genellikle normal retry politikasını tüketmiş veya kalıcı bir sorunla karşılaşmıştır. Önce hata nedeni incelenmeli; veri, yapılandırma veya dış servis problemi düzeltilmelidir. Yeniden işleme yetkili kullanıcı tarafından veya doğrulanmış otomasyon kuralıyla başlatılabilir. İşleyici idempotent olmalı ve daha önce hedefte oluşmuş kayıtları kontrol etmelidir. Hata kuyruğunda deneme sayısı, son hata, iş referansı ve yeniden işleme geçmişi saklanmalıdır.
API entegrasyonunun gerçekten başarılı olduğu nasıl doğrulanır?
Yalnızca HTTP başarı koduna bakmak yeterli değildir. İlgili iş kaydının hedef sistemde doğru alanlar ve doğru tutarla oluştuğu doğrulanmalıdır. Teknik metriklerde başarı oranı, gecikme ve hata türleri izlenirken iş metriklerinde aktarılan, reddedilen, eksik ve mükerrer kayıtlar takip edilmelidir. Kritik entegrasyonlarda kaynak ve hedef sistem kayıtları periyodik mutabakatla karşılaştırılmalıdır. Korelasyon kimliği ve dış referans numarası, tek bir işlemin iki sistemde izlenmesini kolaylaştırır. Böylece görünürde başarılı fakat içerik olarak hatalı aktarımlar da bulunabilir.
