İlk Canlı Ortam Hatanızdan Önce Sahip Olmak İsteyeceğiniz LLM API Hata Politikası

LLM entegrasyonlarında klasik HTTP hata yönetimi (429'da tekrar dene, 500'de geciktirerek dene) canlı ortamda (production) yetersiz kalır. Gerçek bir kriz anında asıl soru "Hata aldık mı?" değil, "Sistem şimdi ne yapmalı?" sorusudur. Hata politikası (Failure Policy), bu iki dünya arasındaki kritik katmandır.

1. Sorun Hata Kodunda Değil

LLM sağlayıcısından gelen bir 429 (Too Many Requests) hatası; dakika başı istek limitini aşmanızdan günlük kotaya, model kapasitesinden geçici sağlayıcı tıkanıklığına kadar pek my farklı nedenden kaynaklanabilir.

Öğrenim: HTTP durum kodları sadece hatanın sınıfını söyler, verilmesi gereken doğru operasyonel kararı söylemez. Dolayısıyla, her 429 hatasına aynı yeniden deneme mantığı uygulanamaz.

2. SDK Hata Yönetimi Bir Olay Politikası Değildir

SDK'ler hata fırlatıp istisnaları yakalamada başarılı olsa da, uygulamanızın o an ne yapacağına karar veremez. İsteklerin kuyruğa alınması, modelin düşürülmesi (fallback) veya bir nöbetçiye uyarı (alert) gönderilmesi kararları iş mantığıyla ilgilidir.

Pratik Çıkarım: SDK'in hata yakalama mekanizmasını doğrudan iş akışlarına bağlamayın. Araya, hata tiplerini analiz eden bağımsız bir karar katmanı koyun.

3. Hata Politikası Nedir?

Hata politikası, ham sağlayıcı hatalarını uygulamamız için anlamlı operasyonel kategorilere dönüştürür. Bu katman şu dört soruya yanıt vermelidir: Ne oldu? Ne kadar eminiz? Sistem ilk olarak ne yapmalı? İlerleyen süreçte insanlar neye bakmalı?

4. Küçük Bir Örnek

Koda entegre edeceğiniz basit bir sınıflandırıcı (classifyLlmFailure), hata nesnesini ve istek bağlamını (context) alır. Yanıt başlıklarını (headers) analiz ederek, limitlerin istek limitinden mi yoksa token limitinden mi kaynaklandığını belirler ve buna göre retry, queue veya fail_closed gibi kararlar üretir.

5. Sadece Hatayı Değil, Politika Kararını Loglayın

Canlı ortam hatalarında ham hata izleri (stack trace) yetersiz kalır. Log dökümlerinde hangi sağlayıcının ve modelin çöktüğü, atanan hata kategorisi ve sistemin aldığı aksiyon (örneğin yeniden deneme süresi ve ilgili runbook kimliği) netçe yer almalıdır.

Pratik Çıkarım: Nöbetçi mühendisin sorunu anlamak için loglar arasında 20 dakika kaybolmasını önleyin. Anlamlı loglama kriz yönetimini hızlandırır.

6. Her Yeniden Denenebilir Hatayı Aynı Şekilde Denemeyin

İstek limitleri için beklemek işe yararken, token limiti aşıldığında büyük bir prompt'u hemen tekrar göndermek anlamsızdır. Özellikle e-posta veya ödeme gibi dış sistemlerde yan etki (side-effect) yaratan işlemlerde körü körüne yeniden deneme yapmak mükerrer işlemlere sebep olur.

7. Runbook'u Koda Yakın Tutun

Tüm hata çözüm adımlarını koda yazarak kod tabanını kirletmeyin. Bunun yerine, hata politikasının kararına ilgili acil durum kılavuzu ID'sini (örn. runbook: llm-timeouts) ekleyin.

Pratik Çıkarım: Bu yöntem, canlı ortam krizlerinde teknik detayları ve iş süreçlerini içeren dökümantasyona doğrudan yönlendirme sağlar.

8. Yeni Entegrasyon Kontrol Listesi

Yeni bir LLM entegrasyonunu canlıya almadan önce şu checklist'i doldurun: İstek ve token limitlerini ayırt edebiliyor muyuz? Zaman aşımı nedeniyle yapılan yeniden denemeler (retry) iş akışı için güvenli mi? Her hata sınıfı için net bir aksiyon planımız ve runbook bağlantımız var mı?

9. Son Söz

LLM API'leri canlı ortamda gerçek yük altında ezilene kadar kusursuz görünür. Asıl zorluk hatayı yakalamak değil, sistemin bu hataya karşı nasıl bir esneklik (resilience) göstereceğidir. İstemci katmanına yerleştireceğiniz küçük bir hata politikası, gelecekteki uykusuz gecelerinizi önleyecektir.

[Orijinal kaynağa buradan ulaşabilirsiniz.](https://dev.to/plasma_01/the-llm-api-failure-policy-i-wish-i-had-before-my-first-production-incident-36i8)