Hata Mesajı Yapılandırma Rehberi

Hata mesajlarının çok katmanlı yapılandırma hiyerarşisini, öncelik sırasını, dinamik şablon sistemini ve koşul bazlı yanıt kurallarını öğrenebilir; farklı senaryolar için en uygun yapılandırma yöntemini belirleyebilirsiniz

Bu sayfa, Apinizer’daki hata mesajı yapılandırma sisteminin tüm katmanlarını, çalışma mantığını ve öncelik sırasını merkezi olarak açıklar. Politika, yönlendirme ve platform genelindeki tüm hata mesajı özelleştirme yöntemleri burada bir arada anlatılmaktadır.

​

Çok Katmanlı Yapılandırma Sistemi

Apinizer, hata mesajlarını dört farklı seviyede yapılandırmanıza olanak tanır. Her seviye, bir üst seviyeyi geçersiz kılabilir (override). Bu sayede hem platform genelinde tutarlı bir hata davranışı tanımlayabilir hem de belirli bir politika veya hata tipi için tamamen farklı bir yanıt döndürebilirsiniz.

​

Yapılandırma Seviyeleri

Seviye	Yapılandırma Yeri	Etki Alanı	Kullanım Amacı
1. Platform Geneli	Sistem Ayarları > Hata Mesajları	Tüm API Proxy’ler ve politikalar	Kuruluş genelinde standart hata formatı belirleme
2. API Proxy / Proxy Grubu	API Proxy Ayarları	Belirli bir API Proxy veya grup	API’ye özel hata yanıt şablonu tanımlama (JSON/XML)
3. Politika / Yönlendirme	Politika veya yönlendirme güncelleme ekranı	Belirli bir politika veya yönlendirme adresi	Politikaya özgü hata mesajı ve şablon tanımlama
4. Hata Satırı Bazlı	Politika veya platform geneli ekrandaki hata satırı	Belirli bir hata tipi	Tek bir hata tipi için özelleştirilmiş yanıt

Bu çok katmanlı yapı, basit bir “tüm hatalarda aynı mesajı göster” ihtiyacından karmaşık “farklı hata tiplerine farklı koşullara göre farklı yanıtlar döndür” senaryolarına kadar her durumu karşılayacak esnekliği sağlar.

​

Hata Mesajı Öncelik Sırası

Bir hata oluştuğunda Gateway aşağıdaki öncelik sırasına göre hangi hata yanıtının döneceğini belirler. İlk eşleşen seviyenin yanıtı kullanılır; alt seviyeler değerlendirilmez.

Öncelik	Kaynak	Açıklama
1 (En yüksek)	Hata satırı bazlı özel mesaj şablonu	Politika, yönlendirme veya platform genelindeki belirli bir hata tipi için tanımlanan şablon tabanlı özel mesaj oluşturucu
2	Politika / yönlendirme geneli özel mesaj şablonu	Politika veya yönlendirme genelinde tanımlanan şablon tabanlı özel mesaj oluşturucu (tüm hata tipleri için)
3	Hata yanıt kuralları	Koşul bazlı yanıt kuralları — istek bilgilerine göre (yol, başlık, metod vb.) farklı hata yanıtları döndürme
4	Hata satırı bazlı alan özelleştirmesi	Politika, yönlendirme veya platform genelindeki satır bazlı Özelleştirilmiş Mesaj, Özelleştirilmiş Hata Kodu, Özelleştirilmiş HTTP Durum Kodu alanları
5	Platform geneli hata mesajı özelleştirmesi	Sistem Ayarları > Hata Mesajları sayfasından yapılan özelleştirmeler
6 (En düşük)	Varsayılan hata mesajı	Sistem tarafından tanımlanan varsayılan hata mesajı

Üst öncelikli bir kaynak tanımlıysa, alt öncelikliler değerlendirilmez. Örneğin bir hata satırı için özel mesaj şablonu aktifse, politika genelindeki şablon, hata yanıt kuralları veya satır bazlı alan özelleştirmeleri dikkate alınmaz.

​

İş Akışı: Bir Hata Nasıl Yanıta Dönüşür?

Aşağıda bir hatanın oluştuğu andan son kullanıcıya döndüğü ana kadarki adımlar özetlenmiştir:

​

Adım 1: Hata Oluşması

Politika, yönlendirme veya API Proxy işleme sırasında bir hata oluşur (örneğin kimlik doğrulama başarısız, kota aşıldı, şema doğrulama hatalı vb.).

​

Adım 2: Varsayılan Değerlerin Belirlenmesi

Sistem, hata tipine karşılık gelen varsayılan HTTP durum kodu, hata kodu ve hata mesajını belirler.

​

Adım 3: Platform Geneli Özelleştirmelerin Kontrolü

Sistem Ayarları > Hata Mesajları sayfasında bu hata tipi için özelleştirilmiş değerler tanımlıysa, varsayılan değerlerin üzerine yazılır.

​

Adım 4: Politika/Yönlendirme Seviyesi Özelleştirme

Hatayı fırlatan politika veya yönlendirme yapılandırmasında bu hata tipi için özelleştirme tanımlıysa uygulanır. Sırasıyla:

1. Hata satırı bazlı özel mesaj şablonu kontrol edilir (en yüksek öncelik)
2. Politika/yönlendirme geneli özel mesaj şablonu kontrol edilir
3. Hata yanıt kuralları sırasıyla değerlendirilir
4. Satır bazlı alan özelleştirmesi uygulanır

​

Adım 5: Hata Yanıt Şablonunun Uygulanması

API Proxy veya Proxy Grubu seviyesinde tanımlı JSON veya XML hata yanıt şablonu varsa, yer tutucular çözümlenerek yanıt gövdesi oluşturulur. Şablon yoksa varsayılan format kullanılır.

​

Adım 6: Yanıtın İstemciye Gönderilmesi

Oluşturulan hata yanıtı, belirtilen HTTP durum kodu ve içerik tipi ile istemciye gönderilir.

​

Yapılandırma Yöntemleri

​

1. Alan Bazlı Özelleştirme (Basit)

Her hata satırı için HTTP durum kodu, hata kodu ve hata mesajı alanlarını özelleştirebilirsiniz. Bu yöntem, belirli bir hatanın sabit bir mesajla döndürülmesini sağlar.

Yapılandırma yerleri:

• Sistem Ayarları > Hata Mesajları (platform geneli)
• Politika güncelleme ekranı > Hata Mesajı Özelleştirme sekmesi (politika bazlı)
• Yönlendirme güncelleme ekranı > Hata Mesajları bölümü (yönlendirme bazlı)

​

2. Şablon Tabanlı Özel Mesaj Oluşturucu (Dinamik)

Serbest metin şablonu yazarak, yer tutucularla istek ve hata bilgilerini otomatik olarak yanıta dahil edebilirsiniz. Bu yöntem, her istek için farklı bilgiler içeren dinamik hata yanıtları oluşturmanızı sağlar.

İki kullanım şekli:

• Hata satırı bazlı: Belirli bir hata tipi için özel şablon (en yüksek öncelik)
• Politika/yönlendirme geneli: Tüm hata tipleri için tek şablon

Yapılandırma alanları:

Alan	Açıklama
Mesaj Şablonu	Serbest metin şablonu. Yer tutucular kullanılabilir
İçerik Tipi (Content-Type)	Yanıtın içerik tipi (varsayılan: application/json;charset=utf-8)
HTTP Durum Kodu	Bu hata oluştuğunda dönecek HTTP durum kodu

​

3. Hata Yanıt Kuralları (Koşullu)

Koşul bazlı yanıt kuralları tanımlayarak, istek bilgilerine göre (yol, başlık, HTTP metodu vb.) farklı hata yanıtları döndürebilirsiniz.

Kuralların çalışma mantığı:

1. Hata oluştuğunda tanımlanan kurallar sıra numarasına göre değerlendirilir
2. İlk eşleşen kuralın şablonu uygulanır
3. Hiçbir kural eşleşmezse sonraki öncelik seviyesine geçilir
4. Koşulsuz bir kural varsayılan kural (catch-all) olarak çalışır ve her zaman eşleşir

Aynı hata satırı için özel mesaj oluşturucu etkin ise, hata yanıt kuralları değerlendirilmez. Özel mesaj oluşturucu daha yüksek önceliğe sahiptir.

Her kuralda tanımlanan alanlar:

Alan	Açıklama
Sıra	Kuralın değerlendirilme sırası (düşük numara = yüksek öncelik)
İsim	Kuralın tanımlayıcı adı
Koşul	İstek bilgilerine göre eşleşme koşulu. Boş bırakılırsa kural koşulsuz çalışır (catch-all)
Mesaj Şablonu	Hata yanıt gövdesini oluşturan şablon
İçerik Tipi	Yanıtın içerik tipi
HTTP Durum Kodu	Yanıtın HTTP durum kodu
Aktif	Kuralın aktif/pasif durumu

​

4. API Proxy Hata Yanıt Şablonu

API Proxy veya Proxy Grubu seviyesinde JSON ve XML formatında hata yanıt şablonları tanımlanabilir. Bu şablonlar, yukarıdaki yöntemlerle özelleştirme yapılmadığında varsayılan hata yanıt formatı olarak kullanılır.

Yapılandırma yeri: API Proxy Ayarları veya API Proxy Grubu ayarları

İstek içerik tipine göre uygun şablon (JSON veya XML) otomatik olarak seçilir.

​

Yer Tutucular ve Değişkenler

Şablon tabanlı mesajlarda ve hata yanıt kurallarında kullanılabilecek yer tutucular:

Standart Yer Tutucular

API Proxy hata yanıt şablonlarında ve hata yanıt kurallarında kullanılır:

Yer Tutucu	Açıklama
#CORRELATIONID#	İstek takip numarası
#FAULTCODE#	Hata kodu
#FAULTMESSAGE#	Hata mesajı
#FAULTMESSAGE_FIRSTLINE#	Hata mesajının ilk satırı
#FAULTSTATUSCODE#	HTTP durum kodu
#RESPONSEFROMAPI#	Backend API yanıtı (varsa)
#RESPONSEFROMAPI_FIRSTLINE#	Backend API yanıtının ilk satırı

Hata Değişkenleri

Şablon tabanlı mesajlarda ve hata yanıt kurallarında kullanılır:

Değişken	Açıklama
#{error.customizedErrorCode}	Özelleştirilmiş hata kodu
#{error.customizedHttpCode}	Özelleştirilmiş HTTP durum kodu
#{error.customizedMessage}	Özelleştirilmiş hata mesajı
#{error.defaultErrorCode}	Varsayılan hata kodu
#{error.defaultMessage}	Varsayılan hata mesajı
#{error.defaultHttpCode}	Varsayılan HTTP durum kodu

İstek Değişkenleri

Değişken	Açıklama
#{request.method}	HTTP metodu (GET, POST vb.)
#{request.uri}	İstek adresi
#{request.contentType}	İstek içerik tipi
#{request.remoteAddress}	İstemci IP adresi
#{request.queryString}	Sorgu parametreleri
#{request.pathInfo}	İstek yolu
#{request.contextPath}	Bağlam yolu

Mesaj ve API Değişkenleri

Değişken	Açıklama
#{message.correlationId}	İstek takip numarası (correlation ID)
#{apiProxy.id}	API Proxy tanımlayıcısı
#{apiProxy.name}	API Proxy adı

Tarih/Saat Değişkenleri

Değişken	Açıklama
#{dateTime.year}	Yıl
#{dateTime.month}	Ay
#{dateTime.dayOfMonth}	Ayın günü
#{dateTime.hour}	Saat
#{dateTime.minute}	Dakika
#{dateTime.second}	Saniye
#{dateTime.timestamp}	Unix zaman damgası
#{dateTime.formattedText}	Biçimlendirilmiş tarih/saat

Ortam Değişkenleri

${DEGISKEN_ADI} formatında ortam değişkenleri kullanılabilir. Ortam değişkenleri hakkında detaylı bilgi için Ortam Değişkenleri sayfasına bakın.

​

Senaryo Örnekleri

​

Senaryo 1: Tüm Hatalarda Standart JSON Formatı

Kuruluş genelinde tüm API hatalarının aynı JSON formatında dönmesini istiyorsanız, platform genelinden alan bazlı özelleştirme yapmanız yeterlidir.

Yapılandırma yeri: Sistem Ayarları > Hata Mesajları

Her hata satırında özelleştirilmiş mesaj, hata kodu ve HTTP durum kodu alanlarını düzenleyin. Tüm API Proxy’ler bu değerleri otomatik olarak kullanacaktır.

​

Senaryo 2: Belirli Bir Politika İçin Farklı Hata Mesajı

Kimlik doğrulama politikasında “Kullanıcı bulunamadı” hatası için özel bir mesaj döndürmek istiyorsanız:

Yapılandırma yeri: Politika güncelleme ekranı > Hata Mesajı Özelleştirme sekmesi

İlgili hata satırında özelleştirilmiş mesaj alanını düzenleyin. Bu, yalnızca bu politikadan fırlatılan hata için geçerli olacaktır.

​

Senaryo 3: Dinamik Hata Yanıtı (Şablon Tabanlı)

Her hatada istek bilgilerini ve takip numarasını içeren detaylı bir yanıt döndürmek istiyorsanız, şablon tabanlı özel mesaj oluşturucuyu kullanın.

Yapılandırma yeri: Politika güncelleme ekranı > Hata Mesajı Özelleştirme sekmesi > ilgili hata satırı > Özelleştir butonu

Örnek şablon:

{
  "error": {
    "code": "#{error.defaultErrorCode}",
    "message": "#{error.defaultMessage}",
    "timestamp": "#{dateTime.formattedText}",
    "correlationId": "#{message.correlationId}",
    "path": "#{request.uri}"
  }
}

Örnek yanıt:

{
  "error": {
    "code": "ERR-035",
    "message": "Authentication policy failed! Invalid API Key/Username and Password pair for Authenticator (SecretManager)!",
    "timestamp": "2026-04-05 14:30:45",
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "path": "/api/v1/users"
  }
}

​

Senaryo 4: İstemci Tipine Göre Farklı Hata Formatı (Koşullu Yanıt Kuralları)

Aynı hata tipi için mobil istemcilere kısa mesaj, web istemcilere detaylı mesaj döndürmek istiyorsanız, hata yanıt kurallarını kullanın.

Yapılandırma yeri: Politika güncelleme ekranı veya Sistem Ayarları > Hata Mesajları > ilgili hata satırı > Özelleştir butonu

Kural 1 (Sıra: 1, Koşul: Header X-Client-Type = mobile):

{
  "code": "#{error.defaultErrorCode}",
  "message": "İstek başarısız"
}

Kural 2 (Sıra: 2, Koşulsuz — catch-all):

{
  "error": {
    "code": "#{error.defaultErrorCode}",
    "message": "#{error.defaultMessage}",
    "correlationId": "#{message.correlationId}",
    "timestamp": "#{dateTime.formattedText}",
    "path": "#{request.uri}",
    "method": "#{request.method}"
  }
}

Bu yapılandırmada mobil istemciler kısa yanıt alırken, diğer tüm istemciler detaylı yanıt alır.

​

Senaryo 5: İş Kuralı STOP Aksiyonunda Özel Mesaj

İş Kuralı politikasında STOP aksiyonu ile akışı durdururken özel bir hata mesajı döndürmek istiyorsanız:

Yapılandırma yeri: İş Kuralı politikası güncelleme ekranı > Hata Mesajı Özelleştirme sekmesi

Politika genelinde özel mesaj şablonunu etkinleştirin ve şablonu yazın:

API çağrınız iş kuralı tarafından reddedildi.
Hata Kodu: #{error.defaultErrorCode}
Zaman: #{dateTime.formattedText}
İstek ID: #{message.correlationId}

​

Bu Yapıyı Ne Kadar Dinamik Kılar?

Apinizer’ın hata mesajı yapılandırma sistemi aşağıdaki nedenlerle son derece esnek ve dinamik bir çözüm sunar:

• Katmanlı geçersiz kılma (override): Her seviye bir üst seviyeyi geçersiz kılabilir. Platform genelinde standart bir davranış tanımlayıp, belirli API’ler veya politikalar için istisna tanımlayabilirsiniz.
• Koşul bazlı yanıt kuralları: Aynı hata tipi için istek bilgilerine göre (başlık, yol, metod, IP vb.) tamamen farklı yanıtlar döndürebilirsiniz.
• Dinamik yer tutucular: Şablonlarda istek bilgileri, hata bilgileri, zaman bilgileri ve ortam değişkenleri kullanarak her istek için farklı içerik oluşturabilirsiniz.
• Üç farklı format desteği: JSON, XML ve düz metin formatlarında hata yanıtları tanımlayabilir; istek içerik tipine göre otomatik format seçimi yapabilirsiniz.
• Merkezi ve dağıtık yönetim: Platform genelinden tek seferde tüm hataları yönetebilir veya politika/yönlendirme bazında bağımsız yapılandırma yapabilirsiniz.

​

İlgili Sayfalar

Hata Mesajları (Sistem Ayarları)

Platform genelinde hata mesajı yönetimi, tüm hata tipleri tablosu

Politika Nedir?

Politika bazlı hata mesajı özelleştirme

API Proxy Ayarları

JSON/XML hata yanıt şablonu yapılandırması

HTTP Yönlendirme

Yönlendirme bazlı hata mesajı özelleştirme

Dinamik Değişkenler

Şablonlarda kullanılabilen tüm değişkenler

İş Kuralı

STOP aksiyonunda özel hata mesajı kullanımı