> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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ı](/tr/admin/system-settings/hata-mesajlari) | Tüm API Proxy'ler ve politikalar | Kuruluş genelinde standart hata formatı belirleme |
| **2. API Proxy / Proxy Grubu** | [API Proxy Ayarları](/tr/develop/api-proxy-konfigurasyonu/settings) | 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](/tr/develop/yonlendirme/http-yonlendirme) 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ı](/tr/admin/system-settings/hata-mesajlari) 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ı](/tr/admin/system-settings/hata-mesajlari) 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ı](/tr/admin/system-settings/hata-mesajlari) (platform geneli)
* Politika güncelleme ekranı > Hata Mesajı Özelleştirme sekmesi (politika bazlı)
* [Yönlendirme](/tr/develop/yonlendirme/http-yonlendirme) 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ı](/tr/develop/api-proxy-konfigurasyonu/settings) veya [API Proxy Grubu](/tr/develop/api-proxy-group-olusturma) 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 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ı |
Ş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 |
| 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 |
| 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ı |
| 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 |
`${DEGISKEN_ADI}` formatında ortam değişkenleri kullanılabilir. Ortam değişkenleri hakkında detaylı bilgi için [Ortam Değişkenleri](/tr/concepts/temel-kavramlar/environment-variable) 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ı](/tr/admin/system-settings/hata-mesajlari)
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:**
```json theme={null}
{
"error": {
"code": "#{error.defaultErrorCode}",
"message": "#{error.defaultMessage}",
"timestamp": "#{dateTime.formattedText}",
"correlationId": "#{message.correlationId}",
"path": "#{request.uri}"
}
}
```
**Örnek yanıt:**
```json theme={null}
{
"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ı](/tr/admin/system-settings/hata-mesajlari) > ilgili hata satırı > Özelleştir butonu
**Kural 1** (Sıra: 1, Koşul: `Header X-Client-Type = mobile`):
```json theme={null}
{
"code": "#{error.defaultErrorCode}",
"message": "İstek başarısız"
}
```
**Kural 2** (Sıra: 2, Koşulsuz — catch-all):
```json theme={null}
{
"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ı](/tr/develop/politikalar/is-kurali) 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
Platform genelinde hata mesajı yönetimi, tüm hata tipleri tablosu
Politika bazlı hata mesajı özelleştirme
JSON/XML hata yanıt şablonu yapılandırması
Yönlendirme bazlı hata mesajı özelleştirme
Şablonlarda kullanılabilen tüm değişkenler
STOP aksiyonunda özel hata mesajı kullanımı