Ana içeriğe atla
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

SeviyeYapılandırma YeriEtki AlanıKullanım Amacı
1. Platform GeneliSistem Ayarları > Hata MesajlarıTüm API Proxy’ler ve politikalarKuruluş genelinde standart hata formatı belirleme
2. API Proxy / Proxy GrubuAPI Proxy AyarlarıBelirli bir API Proxy veya grupAPI’ye özel hata yanıt şablonu tanımlama (JSON/XML)
3. Politika / YönlendirmePolitika veya yönlendirme güncelleme ekranıBelirli bir politika veya yönlendirme adresiPolitikaya özgü hata mesajı ve şablon tanımlama
4. Hata Satırı BazlıPolitika veya platform geneli ekrandaki hata satırıBelirli bir hata tipiTek 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.
ÖncelikKaynakAçıklama
1 (En yüksek)Hata satırı bazlı özel mesaj şablonuPolitika, yönlendirme veya platform genelindeki belirli bir hata tipi için tanımlanan şablon tabanlı özel mesaj oluşturucu
2Politika / yönlendirme geneli özel mesaj şablonuPolitika veya yönlendirme genelinde tanımlanan şablon tabanlı özel mesaj oluşturucu (tüm hata tipleri için)
3Hata 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
4Hata satırı bazlı alan özelleştirmesiPolitika, yönlendirme veya platform genelindeki satır bazlı Özelleştirilmiş Mesaj, Özelleştirilmiş Hata Kodu, Özelleştirilmiş HTTP Durum Kodu alanları
5Platform geneli hata mesajı özelleştirmesiSistem 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:

​
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ı:
AlanAçıklama
Mesaj ŞablonuSerbest 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 KoduBu 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:
AlanAçıklama
SıraKuralın değerlendirilme sırası (düşük numara = yüksek öncelik)
İsimKuralı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 ŞablonuHata yanıt gövdesini oluşturan şablon
İçerik TipiYanıtın içerik tipi
HTTP Durum KoduYanıtın HTTP durum kodu
AktifKuralı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:
API Proxy hata yanıt şablonlarında ve hata yanıt kurallarında kullanılır:
Yer TutucuAçı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ı
Şablon tabanlı mesajlarda ve hata yanıt kurallarında kullanılır:
DeğişkenAçı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
DeğişkenAçı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
DeğişkenAçıklama
#{message.correlationId}İstek takip numarası (correlation ID)
#{apiProxy.id}API Proxy tanımlayıcısı
#{apiProxy.name}API Proxy adı
DeğişkenAçı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
${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ı