Hata mesajında ne olduğunu ve şimdi ne yapılacağını söyle

Kullanıcı çok uzun bir sözleşmeyi asistana ekliyor ve özet istiyor. Birkaç saniye sonra ekranda tek satır beliriyor: “Bir şeyler ters gitti. Lütfen tekrar deneyin.” Altında bir düğme var, kullanıcı ona basıyor. Aynı satır. Sayfayı yeniliyor, dosyayı yeniden ekliyor, bu kez yazdığı açıklama da gidiyor. Üçüncü denemeden sonra ya vazgeçiyor ya da asistanın bozuk olduğuna karar veriyor.

Sistem ne olduğunu biliyordu. Sağlayıcının API'si isteği reddederken bir hata türü ve bir açıklama döndürdü: girdi modelin bağlam penceresine sığmıyordu. Bu hata kaç kez denenirse denensin aynı sonucu verir. Arayüz bu bilgiyi tek bir genel cümleye çevirince kullanıcının elinde tek bir hamle kaldı: aynı isteği yeniden göndermek.

Aynı genel cümle birbirine hiç benzemeyen durumları örtüyor. Sunucu o an yoğun olabilir ve bir dakika sonra her şey çalışır. Kullanıcının kotası dolmuş olabilir ve saatlerce hiçbir deneme işe yaramaz. Girdi çok uzun olabilir ve ancak bölünce geçer. Her biri başka bir hamle istiyor: beklemek, bölmek, sınırın yenilenmesini beklemek, yöneticiye yazmak. Genel mesaj hepsine aynı cevabı veriyor ve çoğu zaman yanlış olanı öneriyor.

Hata mesajı sıradaki hamleyi söylemiyorsa kullanıcı aynı isteği tekrarlar.

Hata yolu ürünün en son yazılan kodu ve çoğu zaman tek bir yakalama bloğuyla yazılıyor. Demo mutlu yolda geçer, hata ekranı “bir şey gösterelim” diye sona eklenir. Bütün istisnalar aynı bloğa düşer, aynı metni basar.

Durum kodu da yanıltıcı. Anthropic'in belgesine göre 429 kodu hem hız sınırına takılan isteğe hem de kullanım kademesinin aylık harcama tavanına ulaşan hesaba dönüyor. Tavandan gelen 429'da yeniden deneme süresini bildiren başlık yok ve istek erişim yeniden açılana kadar başarısız olmaya devam ediyor¹. OpenAI de fatura, harcama ve kota hatalarını yeniden denemenin erişimi geri getirmediğini² yazıyor. Yalnız durum koduna bakan bir arayüz saatler sürecek bir engeli bir dakikalık bir yoğunlukla aynı cümleyle anlatır.

Ekipler ayrıntıdan da çekiniyor. Sağlayıcının ham hata metnini kullanıcıya göstermemek istiyorlar ve bunda haklılar. Ama ham metni saklamak için hatanın türünü de saklamak gerekmiyor. “Belge çok uzun” cümlesi hiçbir iç sistemi açık etmez.

Ölçüm de boşluğu göstermiyor. Panoda hata oranı görünür, hatadan sonra kullanıcının ne yaptığı görünmez. Aynı isteğin art arda gönderilmesi günlüğe ayrı ayrı istekler olarak düşer, bazen kullanım artışı gibi bile okunur. Kimse genel mesajın kaç boşa deneme ürettiğini saymaz.

Hata mesajı iki soruyu cevaplar: ne oldu ve kullanıcı şimdi ne yapabilir. Cevabı vermek için ürün hatanın türünü okur ve her türü ayrı bir cümleye, ayrı bir eyleme bağlar.

1. Türü oku, durum kodunu tek başına yeterli sayma. Sağlayıcının döndürdüğü tür ve kod alanlarını oku: aşırı yük, hız sınırı, kota ya da harcama tavanı, girdi çok uzun, içerik politikası, kimlik doğrulama, ağ. Hepsini ürününün diline çeviren tek bir eşleme tablosu tut. Tanımadığın tür “bilinmeyen hata” olarak görünür ve günlüğe ayrıca yazılır.
2. Ne olduğunu kullanıcının dilinde söyle. “Belge bu sohbetin uzunluk sınırını aşıyor.” “Şu an çok yoğunuz.” “Bu ayki kullanım hakkın doldu.” Teknik kod cümlenin içine girmez, altında küçük bir kimlik olarak durur. Kullanıcı destekle konuşursa işe yarar.
3. Sıradaki hamleyi söyle ve onu düğme yap. Geçici hatada ne kadar bekleneceğini söyle ve yeniden denemeyi ürün kendisi yapsın. Kalıcı hatada yeniden dene düğmesini kaldır, yerine işe yarayacak hamleyi koy: böl, kısalt, sınırın yenileneceği saati göster, yöneticine yaz.
4. Girdiyi koru. Mesaj, ekler ve ayarlar hata ekranından sonra yerinde durur. Kullanıcı kısaltmak için baştan yazmaz, yazdığını düzenler.
5. Sorunun kimde olduğunu ayır. Girdi mi çok uzun, hesabın sınırı mı doldu, yoksa sorun bizde ya da sağlayıcıda mı? Sorun kullanıcının elinde değilse bunu açıkça söyle ve ona iş verme.

Mesaj tek cümle olabilir. Okuyan kullanıcı tekrar denemenin işe yarayıp yaramayacağını o cümleden anlamalı.

Aynı uzun belge, iki hata ekranıyla. Soldaki genel bir cümle ve yeniden dene düğmesi gösteriyor, kullanıcı aynı isteği üç kez gönderiyor ve ekini kaybediyor. Sağdaki sınırı söylüyor, yeniden denemenin sonucu değiştirmeyeceğini yazıyor, işe yarayacak iki yolu öneriyor ve yazılanı yerinde tutuyor.

Anthropic, Claude uygulamasının hata metinlerini yardım sayfasında tek tek yayımlıyor ve metinlerin çoğu bir hamle taşıyor. Kullanım sınırına takılan kullanıcı “5-hour limit reached - resets [time]”³ gibi bir mesajla ne zaman devam edebileceğini görüyor. Uzunluk hatası çözümü mesajın içinde veriyor: daha az ya da daha küçük dosya ekle, yeni bir sohbet başlat. Kapasite mesajı nedeni söylüyor ve kısa süre sonra yeniden denemeyi öneriyor. Yardım sayfası bunun bir kesinti olmadığını ve durum sayfasında görünmeyeceğini ayrıca yazıyor.

Google'ın Gemini uygulaması sınıra yaklaşan kullanıcıyı önceden uyarıyor, sınıra ulaşınca sınırın ne zaman yenileneceğini⁴ söylüyor. Kullanıcı yeniden denemek için saati biliyor.

OpenAI'ın ChatGPT yardım sayfası ters bir örnek. Sayfa “Something went wrong.” mesajını geçici bir sunucu sorununa ya da kullanıcının kendi kurulumundaki bir soruna⁵ işaret edebilecek genel bir hata diye tarif ediyor. Çözüm olarak sayfayı yenilemekten tarayıcı eklentilerini kapatmaya ve ağ değiştirmeye uzanan bir liste veriyor. Mesaj iki nedeni ayırmadığı için listeyi sırayla denemek kullanıcıya kalıyor.

API tarafında ayrım hazır duruyor. Anthropic'in API'si aşırı yükü, hız sınırını, çok büyük isteği ve sunucu hatasını ayrı tür adlarıyla döndürüyor¹. Bağlam penceresini aşan girdi “prompt is too long”⁶ açıklamasıyla geri geliyor. Ayrım API'de var, ama arayüze çoğu zaman ulaşmıyor.

Bu desenin dayanağı yerleşik tasarım kılavuzları ve sağlayıcı belgeleri. Kamuya mal olmuş bir olay ya da AI ürünlerine özgü yayımlanmış bir ölçüm yok.

Nielsen Norman Group'un hata mesajı kılavuzu üç kuralı açıkça koyuyor. “Bir hata oluştu” gibi genel bir mesaj bağlam taşımıyor⁷. Sorunu söylemek de yetmiyor, olası çözümler önerilmeli. Kullanıcı hatayı baştan başlamadan, kendi girdisini düzenleyerek düzeltebilmeli.

Google'ın People + AI Guidebook'u aynı ilkeyi AI ürünlerine taşıyor. Kullanıcının fark ettiği hatalar hakkındaki mesajlar sistemin sınırını olabildiğince somut anlatmalı⁸, sonucun neden verilemediğini söylemeli ve ilerlemek için başka yollar sunmalı. Rehberin ağırlığı kullanıcının hatadan sonra ne yapabileceğinde.

Sağlayıcı belgeleri bir ayrıntı daha ekliyor. Anthropic'in resmi SDK'sı geçici hataları varsayılan olarak iki kez yeniden deniyor¹. Kullanıcı hata mesajını gördüğünde otomatik denemeler çoktan bitmiş oluyor. O noktada “tekrar deneyin” ancak hata gerçekten geçiciyse ve bir süre beklendiyse anlam taşıyor.

Bu kaynaklar hata mesajının ne söylemesi gerektiğini anlatıyor. Genel mesajın kaç boşa deneme ya da kaç terk ürettiğini ölçmüyorlar. O sayıyı kendi günlüğünden çıkarabilirsin.

• Hatadan sonra aynı istek. Hata gören kullanıcının aynı isteği hiç değiştirmeden yeniden gönderme payı, hata türüne göre ayrı. Girdi çok uzun ve kota gibi kalıcı hatalarda bu pay sıfıra yakın olmalı. Yüksekse mesaj kalıcı hatayı geçici gibi anlatıyor.
• Hatadan başarıya giden yol. Hatayı izleyen ilk başarılı isteğe kadar geçen süre ve deneme sayısı. Desen yerindeyse kullanıcı ikinci denemede doğru hamleyi yapıyor.
• Bilinmeyen hata payı. Eşleme tablosuna düşmeyen hataların oranı. Artıyorsa sağlayıcı yeni bir tür eklemiş ya da tablon eksik.
• Kaybolan girdi. Hatadan sonra kullanıcının metni ya da eki yeniden yüklediği oturumlar. Hedef sıfır.
• Destekte hata kimliği. Hatayla ilgili destek taleplerinde hata kimliğinin geçme payı. Kimlik varsa destek ekibi isteği günlükte bulur.

Üç metin var. Denetim promptu ürünündeki AI çağrılarının hata yollarını tarar. Hangi hata türünün hangi metne düştüğünü, girdinin korunup korunmadığını ve yeniden denemenin işe yaramadığı yerde önerilip önerilmediğini raporlar, hiçbir dosyayı değiştirmez. Uygulama promptu hata türlerini kullanıcı mesajlarına ve eylemlere bağlayan tek bir eşleme kurar. Önce planı gösterir, onayınla uygular ve her hata türünü taklit eden testler ekler. Kural kodlama ajanının kendi çalışması için. Bir komut başarısız olduğunda ne olduğunu ve senin ne yapabileceğini yazsın.

Bu depoda bir AI modelini ya da AI API'sini çağıran bir özellik var. Görevin, bu çağrılar başarısız olduğunda kullanıcıya ne gösterildiğini denetlemek. Hiçbir dosyayı değiştirme, yalnız rapor yaz.

1. AI sağlayıcısına giden bütün çağrıları bul (SDK istemcisi, HTTP çağrıları, akış uçları, kuyruk işçileri) ve her birinin hata yolunu izle: try/catch blokları, hata sınırları (error boundary), akış ortasında gelen hata olayları, arka plan işleri.
2. Hata yolunda hangi alanlar okunuyor? Yalnız HTTP durum kodu mu, yoksa sağlayıcının hata türü ve kodu da mı (örnek: rate_limit_error, overloaded_error, insufficient_quota, invalid_request_error, "prompt is too long", context_length_exceeded)? Retry-After başlığı okunuyor mu?
3. Bu türler kullanıcıya giden metinlere nasıl eşleniyor? Farklı türler aynı genel metne mi düşüyor ("Bir şeyler ters gitti", "Bir hata oluştu", "Something went wrong")? Kullanıcıya görünen bütün hata metinlerini ve hangi türden geldiklerini listele.
4. Yeniden deneme nerede öneriliyor ya da otomatik yapılıyor? Kalıcı hatalarda (girdi çok uzun, kota ya da harcama tavanı, kimlik doğrulama, geçersiz istek) da "tekrar dene" düğmesi görünüyor mu? Arayüzdeki yeniden deneme SDK'nın kendi otomatik denemeleriyle üst üste biniyor mu?
5. Hatadan sonra kullanıcının girdisi (mesaj, ekler, seçili ayarlar) korunuyor mu, yoksa form temizleniyor ya da sayfa yenilenince mi kayboluyor?
6. Mesajlar sorunun kimde olduğunu söylüyor mu: kullanıcının girdisi mi, hesabının sınırı mı, ürünün ya da sağlayıcının tarafı mı? Ham sağlayıcı metni, iç adres ya da yığın izi kullanıcıya sızıyor mu?
7. Destek için bir hata kimliği (istek kimliği) kullanıcıya gösteriliyor ve aynı kimlik günlüğe yazılıyor mu?

Rapor biçimi: her bulgu için dosya ve satır, hangi hata türünün hangi metne düştüğü, kullanıcının bu metni görünce büyük olasılıkla ne yapacağı (örnek: bağlam sınırı hatasında "tekrar dene"ye basar, sonuç değişmez) ve önerdiğin düzeltme. Bulguları kullanıcıyı işe yaramayan tekrar denemeye en çok iten yollardan başlayarak sırala.

Bu depodaki AI özelliğine "hata mesajında ne olduğunu ve şimdi ne yapılacağını söyle" desenini uygula. Önce planı göster, onayımı aldıktan sonra kodu değiştir.

Hedef davranış:
1. Sağlayıcının döndürdüğü hata türünü ve kodunu oku, durum koduyla yetinme. Türleri tek bir eşleme tablosunda ürünün kendi sınıflarına çevir: geçici yoğunluk (aşırı yük, sunucu hatası, zaman aşımı), hız sınırı, kota ya da harcama tavanı, girdi çok uzun, içerik politikası, kimlik doğrulama ya da yetki, ağ bağlantısı, bilinmeyen.
2. Her sınıf için kullanıcıya iki şey söyle: ne oldu (kullanıcının dilinde, tek cümle) ve şimdi ne yapabilir. Örnekler: geçici yoğunlukta "Şu an çok yoğunuz, birkaç saniye sonra kendim yeniden deneyeceğim", girdi çok uzunsa "Belge bu sohbetin sınırını aşıyor, bölerek ya da kısaltarak gönderebilirsin", kota dolduysa sınırın yenileneceği saat.
3. Yeniden denemeyi yalnız geçici sınıflarda öner ve Retry-After başlığına uy. Kalıcı sınıflarda "tekrar dene" düğmesini kaldır, yerine işe yarayacak eylemi koy (böl, kısalt, planı gör, yöneticine yaz).
4. Hata ekranından sonra kullanıcının mesajı, ekleri ve ayarları yerinde kalsın. Kullanıcı yazdığını düzenleyerek yeniden gönderebilsin.
5. Mesajın altında kısa bir hata kimliği göster ve aynı kimliği günlüğe yaz. Ham sağlayıcı metnini, iç adresleri ve yığın izini kullanıcıya gösterme.
6. Bilinmeyen türleri genel bir mesaja düşür, ama günlüğe türüyle birlikte ayrıca yaz ki eşleme tablosu zamanla tamamlansın.

Uygularken:
- Kullanıcıya görünen hata metinlerini tek bir dosyada tut, bileşenlere dağıtma.
- SDK'nın kendi yeniden deneme ayarını kontrol et. Arayüzdeki yeniden deneme onunla üst üste binmesin.
- Akışlı (streaming) cevaplarda akış ortasında gelen hata olaylarını da aynı tabloya bağla.
- Bir test ekle: sağlayıcı istemcisini taklit ederek aşırı yük, hız sınırı, kota ve girdi çok uzun hatalarını üret. Her birinde doğru metnin ve doğru eylemin göründüğünü, girdi çok uzun hatasında "tekrar dene" düğmesinin olmadığını ve kullanıcının mesajının korunduğunu doğrula.

## Hata olunca ne olduğunu ve sıradaki hamleyi söyle
- Bir komut, test ya da araç çağrısı başarısız olduğunda hatayı kendi cümlenle anlat: ne oldu, hangi adımda, hangi mesajla. Hata çıktısının ilgili satırını göster.
- Hatanın geçici mi kalıcı mı olduğunu ayır. Zaman aşımı ya da hız sınırı gibi geçici bir hatada bekleyip bir kez yeniden dene. Eksik izin, yanlış yol ya da sözdizimi hatası gibi kalıcı bir hatada aynı komutu tekrarlama.
- "Bir sorun oldu" deyip geçme. Neyin denendiğini ve neyin işe yaramadığını yaz.
- Kullanıcının yapması gereken bir şey varsa (anahtar eklemek, izin vermek, dosyayı küçültmek) bunu tek cümleyle söyle.
- Kodda kullanıcıya görünen bir hata mesajı yazıyorsan aynı ilkeyi uygula: ne olduğunu ve şimdi ne yapılabileceğini yaz, girdiyi silme.

Her hata ayrı bir ekran istemez. Kısa süren ve ürünün kendisinin toparladığı hatalarda (tek bir zaman aşımı, otomatik yeniden denemeyle geçen bir yoğunluk) kullanıcıya hiçbir şey göstermemek doğru olabilir. Mesaj, kullanıcının bir şey yapması ya da beklemesi gerektiğinde görünür.

Ayrıntının da sınırı var. Hatanın türünü söylemek iç sistemi açmak anlamına gelmez. Sağlayıcının ham hata metnini, iç adresleri ya da yığın izini kullanıcıya basma. Destek için kısa bir hata kimliği yeter.

Bu desen reddi kapsamaz. Model bir isteği içerik politikası yüzünden yapmıyorsa bu bir ret ve ret ayrı bir tasarım işi. Cevabın bir kısmının kesildiği durum da ayrı: orada istek başarılı görünür, cevap eksik gelir.

İyi bir mesaj sık tekrarlanan hatayı ortadan kaldırmaz. Kullanıcıların çoğu aynı uzunluk hatasına takılıyorsa girdiyi kendiliğinden bölen bir akış, en iyi yazılmış mesajdan daha çok iş görür.