İş uygulamaları için hata taksonomisi: tutarlı kullanıcı arayüzü ve izleme

Gerçek iş uygulamalarında bir hata taksonomisinin çözdükleri

Hata taksonomisi, hataları adlandırmak ve gruplamak için paylaşılan bir yöntemdir; böylece herkes onları aynı şekilde ele alır. Her ekran ve API kendi mesajlarını üretmek yerine, doğrulama veya yetki gibi küçük bir kategori seti ve bunların kullanıcıya ve izlemeye nasıl yansıyacağına dair kurallar belirlersiniz.

Bu ortak yapı yoksa aynı problem farklı şekillerde görünür. Eksik bir zorunlu alan mobilde “Bad Request” olarak, webde “Bir şeyler yanlış gitti” olarak ve loglarda bir stack trace olarak çıkabilir. Kullanıcılar ne yapacaklarını bilmez; nöbet ekipleri kullanıcı hatası mı, saldırı mı yoksa bir kesinti mi olduğunu tahmin etmekle zaman kaybeder.

Amaç tutarlılıktır: aynı tür hata aynı UI davranışına ve aynı uyarı davranışına yol açar. Doğrulama sorunları ilgili alanı işaret etmeli. İzin sorunları işlemi durdurup hangi erişimin eksik olduğunu açıklamalı. Bağımlılık hataları güvenli bir tekrar seçeneği sunarken izleme doğru ekibi uyarmalı.

Gerçekçi bir örnek: bir satış temsilcisi müşteri kaydı oluşturmaya çalışır, ancak ödeme servisi çalışmıyordur. Uygulamanız sadece 500 dönerse tekrar deneyecek ve daha sonra çoğaltmalar oluşabilir. Açık bir bağımlılık-hatası kategorisiyle UI servisin geçici olarak kullanılamadığını söyler, çift gönderimleri engeller ve izleme doğru ekibi çağırır.

Bu tür hizalanma, bir backend birden fazla istemciyi desteklediğinde en çok önem kazanır. API, web uygulaması, mobil uygulama ve dahili araçlar aynı kategori ve kodlara güvenirse, hatalar rastgele hissettirmeyi bırakır.

Basit bir model: kategori, kod, mesaj, detaylar

Taksonomiler, sıkça karışan dört şeyi ayırdığınızda daha yönetilebilir kalır: kategori (ne tür bir problem), kod (kalıcı tanımlayıcı), mesaj (insan metni) ve detaylar (yapılandırılmış bağlam). HTTP statüsü hâlâ önemlidir ama tüm hikaye olmamalıdır.

Kategori cevaplar: “UI ve izleme nasıl davranmalı?” Bir yerde 403 “auth” anlamına gelebilir, başka bir yerde 403 “policy” olabilir. Kategori davranış hakkındadır, taşıma hakkında değil.

Kod cevaplar: “Tam olarak ne oldu?” Kodlar sabit ve sıkıcı olmalı. Bir düğmenin adını değiştirir veya bir servisi refactor ederseniz kod değişmemeli. Panolar, uyarılar ve destek scriptleri buna dayanır.

Mesaj cevaplar: “Kişiye ne söylemeliyiz?” Mesajın kime yönelik olduğunu belirleyin. Kullanıcıya yönelik mesaj kısa ve nazik olmalı. Destek mesajı sonraki adımları içerebilir. Loglar daha teknik olabilir.

Detaylar cevaplar: “Bunu düzeltmek için neye ihtiyaç var?” Detayları yapılandırılmış tutun ki UI tepki verebilsin. Bir form hatası için bu alan adları olabilir. Bir bağımlılık sorunu için upstream servis adı ve retry-after değeri olabilir.

Birçok ekibin kullandığı sıkıştırılmış yapı şöyle:

{
  "category": "validation",
  "code": "CUSTOMER_EMAIL_INVALID",
  "message": "Enter a valid email address.",
  "details": { "field": "email", "rule": "email" }
}

Özellikler değiştikçe kategorileri küçük ve kararlı tutun, eski kodları yeniden kullanmak yerine yeni kod ekleyin. Bu, UI davranışını, izleme trendlerini ve destek prosedürlerini ürün evrilirken güvenilir kılar.

Temel kategoriler: validation, auth, rate limits, dependencies

Çoğu iş uygulaması her yerde görülen dört kategoriyle başlayabilir. Backend, web ve mobil arasında aynı şekilde adlandırıp ele alırsanız UI tutarlı tepki verir ve izleme okunaklı olur.

Doğrulama (beklenen)

Doğrulama hataları kullanıcı girişi veya iş kuralı başarısız olduğunda ortaya çıkar. Bunlar normaldir ve kolayca düzeltilmeli: zorunlu alan eksik, format hatası veya “indirim %20'yi aşamaz” gibi kurallar. UI tam alanı veya kuralı vurgulamalı, genel bir uyarı göstermemelidir.

Kimlik doğrulama vs yetkilendirme (beklenen)

Auth hataları genellikle iki duruma ayrılır: kimliği doğrulanmamış (oturum kapandı, token eksik) ve yetkisi yok (giriş yapmış ama izin yetersiz). Bunları farklı ele alın. Birinci durum için “Lütfen tekrar giriş yapın” uygundur. İkincide hassas detayları ifşa etmeyin ama yine de net olun: “Faturaları onaylama erişiminiz yok.”

Hız sınırlamaları (beklenen, zaman tabanlı)

Hız sınırlama “çok fazla istek, sonra tekrar deneyin” demektir. Genellikle içe aktarımlar, yoğun panolar veya tekrar tekrar denemeler sırasında görülür. Bir retry-after ipucu (örneğin “30 saniye bekleyin”) ekleyin ve UI'nın sunucuyu vurmaktan vazgeçmesini sağlayın.

Bağımlılık hataları (çoğunlukla beklenmeyen)

Bağımlılık hataları upstream servislerden, zaman aşımı veya kesintilerden gelir: ödeme sağlayıcıları, e-posta/SMS, veritabanları veya dahili servisler. Kullanıcı bunları düzeltemez, bu yüzden UI güvenli bir geri plan sunmalı (taslağı kaydet, sonra dene, destekle iletişime geç).

Temel fark davranıştır: beklenen hatalar normal akışın bir parçasıdır ve kesin geri bildirim ister; beklenmeyen hatalar istikrarsızlığı işaret eder ve uyarılar, correlation ID'ler ve dikkatli loglama tetiklemelidir.

Adım adım: taksonominizi bir atölyede oluşturun

Taksonomi hatırlanacak kadar küçük, ama iki ekip aynı problemi aynı şekilde etiketleyecek kadar katı olmalı.

1) Zaman sınırlayın ve küçük bir set seçin

60–90 dakikalık bir atölye ile başlayın. En sık gördüğünüz hataları listeleyin (kötü giriş, giriş sorunları, çok fazla istek, üçüncü taraf kesintileri, beklenmedik hatalar), sonra bunları 6–12 kategoriye daraltın ki herkes dokümana bakmadan söyleyebilsin.

2) Kararlı bir kod şeması üzerinde anlaşın

Loglarda ve ticketlarda okunabilir kalan bir adlandırma deseni seçin. Kısa tutun, versiyon numaralarından kaçının ve kodları yayımlandıktan sonra kalıcı sayın. Yaygın bir desen kategori öneki artı anlamlı bir etikettir; örn. AUTH_INVALID_TOKEN veya DEP_PAYMENT_TIMEOUT.

Odadan çıkmadan önce her hatanın ne içermesi gerektiğine karar verin: kategori, kod, güvenli mesaj, yapılandırılmış detaylar ve bir trace/request ID.

3) Kategori vs kod için bir kural yazın

Ekipler kategorileri çöplüğe dönüştürdüğünde takılır. Basit bir kural yardımcı olur: kategori “UI ve izleme nasıl tepki verir?” sorusunu yanıtlar; kod “tam olarak ne oldu?” sorusunu yanıtlar. Eğer iki farklı UI davranışı gerektiren iki hata varsa aynı kategoriyi paylaşmamalıdırlar.

4) Kategori başına varsayılan UI davranışı belirleyin

Kullanıcının ne göreceğine karar verin. Doğrulama alanları vurgular. Auth kullanıcıyı oturum açmaya yönlendirir veya erişim mesajı gösterir. Hız sınırlamaları “X saniye bekleyin” gösterir. Bağımlılık hataları sakin bir tekrar ekranı gösterir. Bu varsayılanlar varken yeni özellikler bunlara uyabilir.

5) Gerçek senaryolarla test edin

Beş yaygın akışı (kayıt, ödeme, arama, yönetici düzenleme, dosya yükleme) çalıştırın ve her hatayı etiketleyin. Eğer grup tartışıyorsa genellikle daha net bir kurala ihtiyaç vardır, yeni 20 kod değil.

Doğrulama hataları: kullanıcı için eyleme geçirilebilir yapın

Doğrulama, genellikle anında gösterilmesini istediğiniz hata türüdür. Öngörülebilir olmalı: kullanıcıya neyi düzeltmesi gerektiğini söylemeli ve asla tekrar deneme döngüsü tetiklememelidir.

Alan seviyesi ve form seviyesi doğrulama farklıdır. Alan seviyesi bir girişe (email, telefon, tutar) karşılık gelir. Form seviyesi, girişlerin birleşimiyle ilgili sorunlardır (başlangıç tarihi bitiş tarihinden önce olmalı) veya gerekli önkoşulların eksik olması (kargo yöntemi seçilmemiş). API yanıtınız bu farkı net yapmalı ki UI doğru tepki verebilsin.

Yaygın bir iş kuralı hatası “kredi limiti aşıldı”dır. Kullanıcı geçerli bir sayı girmiş olabilir, ancak işlem hesap durumuna göre izin verilmiyor olabilir. Bunu form seviyesi bir doğrulama hatası olarak ele alın ve açık bir neden ve güvenli bir ipucu verin: “Kullanılabilir limitiniz $500. Tutarı azaltın veya artırım talep edin.” Veritabanı alanları, scoring modelleri veya kural motoru adları gibi iç detayları açığa çıkarmaktan kaçının.

Eyleme geçirilebilir bir yanıt genellikle kararlı bir kod (sadece İngilizce cümle değil), kullanıcı dostu kısa mesaj, isteğe bağlı alan işaretleyicileri ve küçük güvenli ipuçları içerir. Eğer mühendisler için bir kural adı gerekiyorsa, onu loglarda tutun, UI'de değil.

Doğrulama hatalarını sistem hatalarından farklı loglayın. Kalıpları debug edebilmek için yeterli bağlamı kaydedin ama hassas verileri saklamayın. Kullanıcı ID'si, istek ID'si, kural adı veya kod, hangi alanların başarısız olduğu gibi bilgileri tutun. Değerlere gelince genellikle yalnızca “var/yok” veya uzunluk gibi gerekli bilgileri kaydedin ve hassasları maskelenmiş tutun.

UI'da odak, düzeltmeye yönelik olmalı, tekrar denemeye değil. Alanları vurgulayın, kullanıcının yazdıklarını koruyun, ilk hataya kaydırın ve otomatik tekrarları devre dışı bırakın. Doğrulama hataları geçici değildir; “tekrar deneyin” zaman kaybıdır.

Auth ve izin hataları: güvenlik ve netlik arasında denge kurun

Kimlik doğrulama ve yetkilendirme hataları kullanıcıya benzer gelebilir, ama güvenlik, UI akışı ve izleme için farklı anlamları vardır. Bunları ayırmak web, mobil ve API istemcileri arasında davranışı tutarlı kılar.

Oturumsuzluk uygulamanın kullanıcının kimliğini doğrulayamadığı anlamına gelir. Tipik nedenler eksik kimlik bilgisi, geçersiz token veya süresi dolmuş oturumdur. Forbidden ise kullanıcının bilindiği ama eylemi yapmaya izni olmadığı durumdur.

Oturum süresi dolması en yaygın kenar durumdur. Eğer refresh token destekliyorsanız bir kez sessiz yenileme deneyin, sonra orijinal isteği tekrar deneyin. Yenileme başarısız olursa oturumsuz hata döndürün ve kullanıcıyı tekrar girişe yönlendirin. Döngülerden kaçının: bir yenileme denemesinden sonra durun ve net bir sonraki adım gösterin.

UI davranışı tahmin edilebilir olmalı:

• Oturumsuz: giriş iste, kullanıcının yaptığı işi koru
• Forbidden: sayfada kal ve erişim mesajı göster; güvenli bir eylem sun (örn. “erişim iste”)
• Hesap devre dışı/iptal: çıkış yaptır ve desteğin yardım edebileceğini kısa bir mesajla göster

Denetim (auditing) için “kim neyi denedi ve neden engellendi” sorusunu cevaplayacak kadar log tutun ama sırları ifşa etmeyin. Faydalı bir kayıt kullanıcı ID (biliniyorsa), tenant/workspace, eylem adı, kaynak identifier, zaman damgası, istek ID ve politika kontrol sonucu (izin/verme) içerebilir. Ham token ve parolaları loglara koymayın.

Kullanıcıya gösterilen mesajlarda rol adları, izin kuralları veya dahili politika yapısını ifşa etmeyin. “Faturaları onaylama erişiminiz yok” mesajı, “Sadece FinanceAdmin faturaları onaylayabilir” demekten daha güvenlidir.

Hız sınırı hataları: yük altında tahmin edilebilir davranış

Hız sınırları bir hata değil, güvenlik ağıdır. Bunları birinci sınıf kategori olarak ele alın ki UI, loglar ve uyarılar trafik arttığında tutarlı tepki versin.

Hız sınırlamaları genelde birkaç şekilde ortaya çıkar: kullanıcı başına (biri çok hızlı tıklıyor), IP başına (bir ofis ağı arkasındaki çok sayıda kullanıcı) veya API anahtarı başına (tek bir entegrasyon işi kontrolden çıktı). Neden fark ettirir; çünkü çözüm farklıdır.

İyi bir hız-limit yanıtı neler içermeli

İstemcilerin iki şeye ihtiyacı vardır: sınırlandıkları ve ne zaman tekrar deneyebilecekleri bilgisi. HTTP 429 döndürün ve net bir bekleme süresi verin (ör. Retry-After: 30). Ayrıca RATE_LIMITED gibi kararlı bir hata kodu ekleyin ki panolar olayları gruplayabilsin.

Mesaj sakin ve spesifik olmalı. “Çok fazla istek” teknik olarak doğru ama yardımcı değil. “Lütfen 30 saniye bekleyin ve tekrar deneyin” beklenti koyar ve tekrar tıklamaları azaltır.

UI tarafında hızlı tekrarları engelleyin. Basit bir desen, eylemi bekleme süresi boyunca devre dışı bırakmak, kısa bir geri sayım göstermek ve sayaç bittiğinde bir güvenli tekrar sunmaktır. Kullanıcıların verinin kaybolduğunu düşünmelerine yol açacak ifadelerden kaçının.

İzleme tarafında ekipler genellikle aşırı tepki verir. Her 429 için birini çağırmayın. Oranları takip edin ve uç nokta, tenant veya API anahtarı için ani sıçramalarda uyarı verin.

Backend davranışı da öngörülebilir olmalı. Otomatik tekrarlar için üssel geri çekilme (exponential backoff) kullanın ve tekrarları idempotent yapın. “Fatura oluştur” eylemi, ilk istek gerçek anlamda başarılı olmuşsa iki fatura yaratmamalıdır.

Bağımlılık hataları: kesintileri kaosa dönüştürmeden ele alın

Bağımlılık hataları kullanıcıların daha iyi girişle düzeltemeyeceği durumlardır. Kullanıcı her şeyi doğru yapmıştır ama bir ödeme ağ geçidi zaman aşımı vermiş, veritabanı bağlantısı düşmüş veya upstream servis 5xx dönmüştür. Bunları ayrı bir kategori olarak ele alın ki UI ve izleme tahmin edilebilir davransın.

Önce yaygın hata şekillerini isimlendirin: zaman aşımı, bağlantı hatası (DNS, TLS, reddedildi) ve upstream 5xx (bad gateway, service unavailable). Temel sebebi bilmiyorsanız bile ne olduğunu yakalayabilir ve tutarlı yanıt verebilirsiniz.

Tekrar mı yoksa hızlı başarısızlık mı

Tekrarlar kısa kesintiler için yardımcı olur ama kesintiyi kötüleştirebilir. Her ekip aynı kararı vermesi için basit kurallar kullanın.

• Hata muhtemelen geçici ise tekrar dene: zaman aşımı, bağlantı sıfırlama, 502/503
• Kullanıcı kaynaklı veya kalıcı durumlarda hızlı başarısızlık: bağımlılıktan gelen 4xx, geçersiz kimlik bilgileri, eksik kaynak
• Denemeleri sınırlayın (ör. 2–3 deneme) ve küçük bir backoff ekleyin
• İdempotent olmayan işlemleri idempotency anahtarı olmadan tekrar denemeyin

UI davranışı ve güvenli geri planlar

Bağımlılık başarısız olduğunda kullanıcıya ne yapabileceğini söyleyin ve suçu kullanıcıya atmayın: “Geçici bir sorun. Lütfen sonra yeniden deneyin.” Güvenli bir geri plan varsa bunu sunun. Örnek: Stripe çalışmıyorsa kullanıcının siparişi “Ödeme beklemede” olarak kaydetmesine izin verin ve sepeti kaybetmek yerine e-posta onayı gönderin.

Ayrıca kullanıcıları çift gönderimden koruyun. Kullanıcı “Öde”ye iki kez tıklarsa sistem bunu tespit etmelidir. Create-and-charge akışları için idempotency anahtarları kullanın veya “sipariş zaten ödendi” gibi durum kontrolleri ile tekrar çalıştırmadan önce kontrol edin.

İzleme için, “Hangi bağımlılık başarısız oluyor ve ne kadar kötü?” sorusunu hızlı cevaplayacak alanları loglayın: bağımlılık adı, endpoint veya işlem, süre ve nihai sonuç (timeout, connect, upstream 5xx). Bu, uyarıları ve panoları gürültüsüz ve anlamlı kılar.

Kanallar arasında izleme ve UI'yi tutarlı kılın

Taksonomiler yalnızca her kanal aynı dili konuştuğunda işe yarar: API, web UI, mobil uygulama ve loglar. Aksi halde aynı problem beş farklı mesaj olarak görünür ve kimse bunun kullanıcı hatası mı yoksa gerçek bir kesinti mi olduğunu bilemez.

HTTP statü kodlarını ikincil bir katman olarak ele alın. Proxy'lar ve temel istemci davranışı için yardımcı olurlar, ama anlam kategori ve kod tarafından taşınmalıdır. Bir bağımlılık zaman aşımı yine 503 olabilir, ama kategori UI'ye “Tekrar dene” teklif ettirir ve izlemeye nöbeti çağırması gerektiğini söyler.

Her API'niz aynı standart hata şeklini döndürmeli, kaynak farklı olsa bile (veritabanı, auth modülü, üçüncü taraf API). Basit bir şekil UI işleme ve panoları tutarlı tutar:

{
  "category": "dependency",
  "code": "PAYMENTS_TIMEOUT",
  "message": "Payment service is not responding.",
  "details": {"provider": "stripe"},
  "correlation_id": "9f2c2c3a-6a2b-4a0a-9e9d-0b0c0c8b2b10"
}

Correlation ID'ler “kullanıcı bir hata gördü” ile “onu izleyebiliriz” arasındaki köprüdür. correlation_id'yi UI'de gösterin (kopyalama düğmesi yardımcı olur) ve backend'de her zaman loglayın ki bir isteği servisler arasında izleyebilin.

UI'de neyin gösterileceği ile sadece loglarda tutulacaklar arasında ortak bir güvenli sınır üzerinde anlaşın. Pratik bir ayrım: UI kategori, net bir mesaj ve bir sonraki adımı alır; loglar teknik hata detayları ve istek bağlamını alır; her ikisi correlation_id ve kararlı hata kodunu paylaşır.

Tutarlı bir hata sistemi için hızlı kontrol listesi

Tutarlılık en iyi haliyle sıkıcıdır: her kanal aynı şekilde davranır ve izleme gerçeği söyler.

Önce backend'i kontrol edin, arka plan işleri ve webhooklar dahil. Hangi alan isteğe bağlısa insanlar atlar ve tutarlılık bozulur.

• Her hata bir kategori, kararlı bir kod, kullanıcıya güvenli bir mesaj ve bir trace ID içerir.
• Doğrulama problemleri beklenen olduğu için nöbet uyarılarını tetiklemez.
• Auth ve izin sorunları güvenlik paterni için takip edilir ama kesinti gibi ele alınmaz.
• Hız limitleri bir bekleme ipucu içerir (ör. beklenmesi gereken saniye) ve uyarıları spamlemez.
• Bağımlılık hataları bağımlılık adını artı zaman aşımı veya durum detaylarını içerir.

Sonra UI kurallarını kontrol edin. Her kategori tek bir öngörülebilir ekran davranışına eşlenmeli ki kullanıcı bir sonraki adımı tahmin etmek zorunda kalmasın: doğrulama alanları vurgular, auth oturum açtırır veya erişimi gösterir, hız limitleri sakin bir bekleme gösterir, bağımlılık hataları tekrar seçeneği ve mümkünse bir geri plan sunar.

Basit bir test staging'de her kategoriden bir hata tetiklemek ve web, mobil ve admin panelinde aynı sonucu aldığınızı doğrulamaktır.

Yaygın hatalar ve pratik sonraki adımlar

Hata sistemini sonradan düşünmek onu kırmanın en hızlı yoludur. Farklı ekipler aynı problem için farklı kelimeler, farklı kodlar ve farklı UI davranışları kullanır. Taksonomi çalışması tutarlı kaldıkça geri dönüş sağlar.

Yaygın başarısızlık kalıpları:

• İç istisna metnini kullanıcılara sızdırmak. İnsanları şaşırtır ve hassas bilgileri ifşa edebilir.
• Her 4xx'i “validation” olarak etiketlemek. Eksik izin bir alan eksikliğinin tersi değildir.
• Her özellik için yeni kodlar icat etmek. Sonuçta aynı 5 şeyi ifade eden 200 kodunuz olur.
• Yanlış hatalar için tekrar denemek. Bir izin hatasını veya geçersiz e-posta adresini tekrar denemek sadece gürültü oluşturur.

Basit bir örnek: bir satış temsilcisi “Müşteri oluştur” formunu gönderir ve 403 alır. UI tüm 4xx'leri doğrulama olarak ele alırsa rastgele alanları vurgular ve “girişleri düzeltin” der; oysa gerçekte erişim gerektiğini söylemelidir. İzleme sonra “doğrulama sorunlarında” sıçrama gösterir ama gerçek sorun rollerle ilgilidir.

Kısa bir atölyede yapılacak pratik adımlar: bir sayfa taksonomi dokümanı yazın (kategoriler, ne zaman kullanılacağı, 5–10 kanonik kod), mesaj kurallarını tanımlayın (kullanıcıya ne gösterilir, loglara ne gider), yeni kodlar için hafif bir inceleme kapısı kurun, kategoriye göre tekrar kuralları belirleyin ve ardından uçtan uca uygulamayı hayata geçirin (backend yanıtı, UI eşlemesi, izleme panoları).

Eğer AppMaster (appmaster.io) ile inşa ediyorsanız, bu kuralları tek bir yerde merkezileştirmek backend, web ve native mobil uygulamalarda aynı kategori ve kod davranışının sürdürülmesine yardımcı olur.