REST ve SOAP Servis Entegrasyonlarında Hata Yönetimi

Kurumsal yazılım projelerinde dış servis entegrasyonları çoğu zaman sistemin en kritik noktalarından biridir. Uygulama kendi içinde sağlıklı çalışsa bile bağlı olduğu servislerde timeout, hatalı response, business hata kodu, bağlantı problemi veya geçici kesinti yaşanabilir.

REST veya SOAP fark etmeksizin iyi bir entegrasyon yapısında sadece başarılı senaryo değil, hata senaryoları da tasarımın merkezinde olmalıdır.

Bu yazıda servis entegrasyonlarında hata yönetimini backend geliştirici gözüyle ele alıyorum.

Hata Yönetimi Neden Önemlidir?

Dış servis entegrasyonları genellikle uygulamanın kontrolü dışındaki sistemlere bağımlıdır. Banka servisleri, kamu servisleri, ödeme kuruluşları, sigorta servisleri veya kurum içi farklı sistemler her zaman aynı performans ve cevap kalitesiyle çalışmayabilir.

İyi tasarlanmamış hata yönetimi şu problemlere yol açabilir:

• Kullanıcıya anlamsız hata mesajı gösterilmesi
• Aynı işlemin birden fazla kez çalışması
• İşlem durumunun belirsiz kalması
• Operasyon ekiplerinin hatayı analiz edememesi
• Loglardan gerçek sebebin bulunamaması
• Finansal veya kritik iş süreçlerinde veri tutarsızlığı oluşması

Bu nedenle entegrasyon geliştirirken “servis başarılı dönerse ne olur?” kadar “servis cevap vermezse ne olur?” sorusu da cevaplanmalıdır.

Sık Karşılaşılan Hata Türleri

Dış servis entegrasyonlarında karşılaşılan hataları birkaç ana gruba ayırabiliriz.

1. Teknik Hatalar

Teknik hatalar genellikle servis çağrısı sırasında oluşur.

Timeout
Connection refused
DNS problemi
SSL hatası
Authentication hatası
Beklenmeyen HTTP status code
Response parse edilemedi

Bu tip hatalarda servis sağlayıcıdan anlamlı bir business response alınamamış olabilir.

2. Business Hatalar

Business hatalar, servis teknik olarak cevap verdiği halde işlemin iş kuralı nedeniyle başarısız olmasıdır.

Örnekler:

Kimlik doğrulama başarısız
Müşteri bulunamadı
Limit yetersiz
Geçersiz poliçe bilgisi
Geçersiz işlem tipi
Mükerrer kayıt

Bu hatalar genellikle kullanıcıya veya operasyon ekibine daha anlamlı şekilde aktarılmalıdır.

3. Belirsiz Durumlar

En kritik senaryo budur.

Örneğin servis çağrısı yapıldı, karşı tarafa istek ulaştı ama uygulama timeout aldı. Bu durumda işlem karşı tarafta oluşmuş olabilir veya hiç oluşmamış olabilir.

Bu tip durumlar için status inquiry, sorgulama veya mutabakat mekanizması gerekir.

REST ve SOAP Arasındaki Farklar

REST servislerinde hata bilgisi çoğunlukla HTTP status code ve JSON response içinde taşınır.

400 Bad Request
401 Unauthorized
404 Not Found
409 Conflict
500 Internal Server Error

SOAP servislerinde ise hata bilgisi genellikle SOAP Fault veya response body içindeki özel hata kodlarıyla gelir.

<soap:Fault>
  <faultcode>Server</faultcode>
  <faultstring>Service unavailable</faultstring>
</soap:Fault>

Fakat pratikte hem REST hem SOAP servislerde sağlayıcıya özel response modelleri olur. Bu yüzden entegrasyon katmanında ortak bir hata modeli oluşturmak önemlidir.

Ortak Hata Modeli Kullanmak

Uygulamanın her sağlayıcının hata formatını doğrudan kullanması kodu karmaşıklaştırır. Bunun yerine entegrasyon katmanında ortak bir hata modeli kullanılabilir.

Örnek model:

IntegrationError
 ├── Provider
 ├── ErrorCode
 ├── ErrorMessage
 ├── ErrorType
 ├── IsRetryable
 ├── RawResponse
 └── CorrelationId

Bu yapı sayesinde farklı servislerden gelen hatalar uygulama içinde standart şekilde yönetilebilir.

Örnek hata tipleri:

Technical
Business
Validation
Authentication
Timeout
Unknown

Bu ayrım retry, kullanıcı mesajı ve operasyonel aksiyonlar için önemlidir.

Correlation Id Kullanımı

Dış servis entegrasyonlarında correlation id kullanmak büyük kolaylık sağlar.

Bir işlem uygulama içinde başladığında tekil bir correlation id üretilir ve tüm loglarda bu id taşınır.

API Request
 └── Application Service
     └── Integration Service
         └── External Provider Call

Tüm bu adımlarda aynı correlation id kullanılırsa, bir hatayı loglarda uçtan uca takip etmek çok daha kolay olur.

Özellikle canlı sistemlerde “bu işlem neden başarısız oldu?” sorusuna hızlı cevap verebilmek için correlation id kritik önemdedir.

Loglama Nasıl Yapılmalı?

Servis entegrasyonlarında loglama sadece exception mesajını yazmak değildir.

Aşağıdaki bilgiler mümkün olduğunca kayıt altına alınmalıdır:

• CorrelationId
• Request zamanı
• Response zamanı
• Duration
• Provider adı
• Endpoint veya işlem tipi
• HTTP status code
• Business hata kodu
• Hata mesajı
• Request payload özeti
• Response payload özeti
• Retry sayısı

Ancak hassas veriler loglanmamalıdır. Kimlik bilgileri, token, şifre, kart bilgisi, CVV veya kişisel veriler maskelenmelidir.

Örnek maskeleme yaklaşımı:

TCKN: 12345678901 → 123******01
Card: 5400 1234 5678 9999 → 5400 **** **** 9999
Token: eyJhbGciOi... → ***masked***

Retry Stratejisi

Retry mekanizması her entegrasyonda dikkatli tasarlanmalıdır.

Retry yapılabilecek durumlar:

• Geçici network hatası
• Timeout
• 503 Service Unavailable
• 504 Gateway Timeout
• Rate limit sonrası beklemeli deneme

Retry yapılmaması gereken durumlar:

• Validation hatası
• Yetkilendirme hatası
• Geçersiz input
• Business kural nedeniyle başarısız işlem
• Mükerrer işlem riski taşıyan finansal operasyonlar

Özellikle ödeme, kredi, poliçe oluşturma veya kayıt yaratan işlemlerde kör retry yapılmamalıdır. Önce işlem durumunun sorgulanması gerekebilir.

Timeout Değerleri

Timeout değerleri sonsuz veya çok yüksek olmamalıdır. Her servis için makul timeout değerleri belirlenmelidir.

Örneğin:

Kısa sorgu servisleri: 5-10 saniye
Daha ağır operasyonlar: 15-30 saniye
Dosya veya yoğun işlem servisleri: iş ihtiyacına göre ayrı değerlendirme

Timeout süresi belirlenirken kullanıcı deneyimi, servis sağlayıcı SLA’i ve operasyonel gereksinimler birlikte düşünülmelidir.

Circuit Breaker Yaklaşımı

Bir dış servis uzun süre hata dönüyorsa uygulamanın sürekli aynı servisi zorlaması doğru değildir.

Circuit breaker mantığı ile belirli sayıda hata sonrası servis çağrısı kısa süreli durdurulabilir. Böylece hem uygulama kaynakları korunur hem de kullanıcıya daha hızlı ve kontrollü dönüş yapılır.

Basit akış:

1. Servis hataları artar
2. Circuit open olur
3. Belirli süre servis çağrısı yapılmaz
4. Süre sonunda test çağrısı yapılır
5. Servis düzeldiyse circuit close olur

Bu yaklaşım özellikle yoğun trafikli sistemlerde faydalıdır.

Response Normalizasyonu

Farklı servislerin response formatı farklı olabilir. Uygulama içinde bu farkları yaymak yerine entegrasyon katmanında normalize etmek daha sağlıklıdır.

Örnek:

Provider A → code: "00", message: "Approved"
Provider B → resultCode: "SUCCESS"
Provider C → status: true

Uygulama içinde ortak response:

IntegrationResult
 ├── IsSuccess
 ├── Status
 ├── ErrorCode
 ├── ErrorMessage
 ├── ProviderReference
 └── RawData

Bu yapı uygulama servislerini provider bağımlılığından korur.

.NET Tarafında Pratik Mimari

.NET projelerinde entegrasyon katmanı için sade bir yapı şu şekilde olabilir:

Application
 ├── Services
 └── UseCases

Infrastructure
 ├── Integrations
 │   ├── Providers
 │   │   ├── ProviderAClient
 │   │   ├── ProviderBClient
 │   │   └── ProviderCClient
 │   ├── Models
 │   ├── Mappers
 │   └── ErrorHandling
 └── Logging

Her provider client kendi request/response modelini bilir. Application katmanı ise ortak result modeliyle çalışır.

Bu yaklaşım hem test edilebilirliği artırır hem de yeni servis eklemeyi kolaylaştırır.

Operasyonel İzlenebilirlik

Canlı sistemlerde entegrasyon hatalarının sadece teknik ekip tarafından değil, operasyon ekipleri tarafından da anlaşılabilir olması gerekir.

Bu nedenle loglara ek olarak şu yapılar faydalıdır:

• Entegrasyon işlem kayıtları
• Dashboard veya takip ekranı
• Hata kodu açıklamaları
• Tekrar deneme / manuel sorgulama aksiyonları
• Provider bazlı başarı/hata oranları
• Ortalama response süresi

Bu tip izlenebilirlik mekanizmaları, canlı sistemlerde sorun çözme süresini ciddi şekilde azaltır.

Sonuç

REST ve SOAP servis entegrasyonlarında başarılı response almak kadar hata senaryolarını doğru yönetmek de önemlidir.

Sağlıklı bir entegrasyon yapısı şu özelliklere sahip olmalıdır:

• Ortak hata modeli
• Correlation id ile uçtan uca izlenebilirlik
• Hassas veri maskeleme
• Kontrollü retry
• Timeout yönetimi
• Circuit breaker yaklaşımı
• Response normalizasyonu
• Operasyonel takip ve loglama

Backend geliştirici açısından amaç sadece servisi çağırmak değil, servisin başarısız olduğu durumlarda da sistemin kontrollü, izlenebilir ve güvenli şekilde davranmasını sağlamaktır.