API Üzerinden AI Servis Tüketimi ve Hata Yönetimi

Bir AI servisini API üzerinden çağırmak ilk bakışta birkaç satırlık HTTP isteği kadar basit görünür. Gerçek production ortamında ise rate limit, timeout, yarım kalan stream, beklenmeyen JSON, provider kesintisi, tekrar eden istek ve maliyet artışı aynı anda karşınıza çıkabilir. On yıllık yazılım ve entegrasyon projelerinde gördüğüm temel fark şudur: demo çalışan kod ile dayanıklı production entegrasyonu arasında ciddi bir mühendislik katmanı bulunur. API Üzerinden AI Servis Tüketimi ve Hata Yönetimi yaklaşımı yalnızca hata olduğunda retry yapmak değil, hatayı doğru sınıflandırmak, tekrar davranışını kontrol etmek, kullanıcı deneyimini korumak ve maliyeti gözlem altında tutmak anlamına gelir. Bu rehberde AI API entegrasyonu ve hata yönetimi nasıl yapılır sorusundan başlayarak 429 rate limit, timeout, exponential backoff, circuit breaker, fallback, queue, observability, test ve production mimarisine kadar uygulanabilir bir yapı kuracağız.

API Üzerinden AI Servisi Tüketmek Nedir?

API üzerinden AI servisi tüketmek, uygulamanızın bir yapay zeka modeline doğrudan model dosyası çalıştırmadan ağ üzerinden istek gönderip yanıt almasıdır. Uygulama prompt, model adı, generation ayarları ve gerekli metadata ile HTTP çağrısı yapar. AI servisi bu isteği işler, sonucu JSON veya stream biçiminde döndürür. Bu yapı geliştiriciye model altyapısını doğrudan yönetmeden AI yeteneklerini ürüne ekleme imkanı verir. Buna karşılık ağ gecikmesi, provider hatası, kota, güvenlik ve değişken yanıt yapısı gibi yeni operasyon sorumlulukları ortaya çıkar.

AI API Nedir ve Nasıl Çalışır?

AI API, uygulamanın bir model servisinin yeteneklerine standart istek yapısı üzerinden erişmesini sağlayan arayüzdür. İstemci belirli endpoint'e authentication bilgisi ve request payload gönderir. Provider tarafında model inference yapılır ve çıktı istemciye response olarak iletilir. Kullanılan modele göre chat, embedding, image, speech veya tool calling gibi farklı endpoint türleri bulunabilir. Production entegrasyonunda yalnızca başarılı response değil error code, latency, token usage ve retry header bilgileri de uygulama tasarımının parçası olmalıdır.

Uygulama ile AI Servisi Arasındaki İstek–Yanıt Akışı

İstek akışı genellikle kullanıcıdan gelen input'un backend tarafından doğrulanmasıyla başlar. Backend prompt veya structured payload hazırlar ve AI client katmanı üzerinden provider'a gönderir. Provider isteği kabul eder, model inference gerçekleştirir ve response üretir. Uygulama dönen veriyi validation katmanından geçirip kullanıcıya veya downstream sisteme sunar. Hata yönetimi bu zincirin her adımında ayrı ele alınmalıdır çünkü network problemi ile geçersiz model çıktısı aynı hata sınıfına ait değildir.

REST API, SDK ve API Gateway Yaklaşımları

REST API doğrudan HTTP çağrılarıyla en temel entegrasyon yöntemidir. SDK provider'a özgü authentication, retry veya streaming ayrıntılarını daha kullanışlı interface arkasına alabilir. API Gateway ise birden fazla model ve provider'ı ortak bir endpoint arkasında toplamak için kullanılır. Küçük projelerde resmi SDK hızlı başlangıç sağlar, kurumsal projelerde provider abstraction ve gateway uzun vadede daha fazla esneklik sunar. Seçim yapılırken SDK'nın otomatik retry davranışı ve hata tiplerinin uygulama tarafındaki policy ile çakışıp çakışmadığı mutlaka kontrol edilmelidir.

Senkron, Asenkron ve Streaming AI İstekleri

Senkron istek kullanıcı aynı bağlantı üzerinde final yanıtı beklediğinde kullanılır. Asenkron model uzun süren işlemi queue veya job mantığıyla arka planda yürütür ve sonuç daha sonra alınır. Streaming yaklaşımı model çıktısını token veya chunk geldikçe kullanıcıya iletir. Chat arayüzlerinde streaming algılanan latency'yi belirgin biçimde iyileştirir. Uzun document processing veya batch generation gibi görevlerde ise asenkron job mimarisi daha güvenilir olabilir.

Senkron istek ne zaman kullanılmalı?

Kısa ve öngörülebilir AI işlemlerinde senkron istek uygundur. Kullanıcı form gönderip birkaç saniye içinde sınıflandırma veya kısa metin sonucu bekliyorsa ek job altyapısı gereksiz olabilir. Timeout değeri request süresine göre makul sınırda tutulmalıdır. İstek sonucu downstream sistemde side effect oluşturmuyorsa retry yönetimi daha kolay olur. Uzun generation işlerinde senkron bağlantının dakikalarca açık kalması yerine farklı mimari değerlendirilmelidir.

Streaming ne zaman tercih edilmeli?

Streaming özellikle chat, metin üretimi ve kullanıcıya hızlı geri bildirim verilmesi gereken uygulamalarda yararlıdır. Kullanıcı ilk token'ı birkaç saniye içinde gördüğünde toplam yanıt uzun olsa bile sistem daha hızlı hissedilir. Bunun karşılığında stream ortasında bağlantı kopması ve partial response yönetimi gerekir. Proxy ve load balancer buffering ayarları streaming davranışını bozabilir. Client disconnect ve yeniden deneme stratejisi baştan tasarlanmalıdır.

Uzun süren AI işlemleri nasıl yönetilmeli?

Uzun süren işler request thread içinde tutulmak yerine queue tabanlı worker sistemiyle yönetilebilir. Kullanıcıya job ID döndürülür ve status endpoint üzerinden ilerleme takip edilir. Worker provider'a çağrı yapar, retry policy uygular ve sonucu kalıcı storage'a yazar. Başarısız görevler belirli retry sayısından sonra dead letter queue'ya taşınabilir. Bu yapı büyük belge analizi, toplu embedding veya uzun rapor üretimi gibi görevlerde daha dayanıklı olur.

Bir AI API Entegrasyonunun Temel Bileşenleri

Production entegrasyonun temelinde endpoint, authentication, model seçimi, request payload, response parsing ve timeout yapılandırması bulunur. Bunlardan biri yanlış tasarlandığında hata yönetimi de zorlaşır. Örneğin model seçimi uygulama kodunun her yerine dağılmışsa fallback sırasında değişiklik maliyeti büyür. Token kullanımı ölçülmüyorsa retry nedeniyle oluşan maliyet artışı fark edilmez. Sağlam entegrasyon bu bileşenleri ortak client veya service katmanında toplar.

API Endpoint

Endpoint uygulamanın bağlandığı servis adresidir ve mümkün olduğunca merkezi configuration üzerinden yönetilmelidir. Development, staging ve production ortamları farklı endpoint kullanabilir. Provider değişimi veya gateway migration durumunda istemcilerin tamamında kod değiştirmek istenmez. Endpoint health ve DNS çözümleme problemleri network error sınıfına dahil edilmelidir. Hard-coded URL yerine environment veya configuration management tercih edilmelidir.

API Key ve Authentication

API key istemcinin provider tarafından doğrulanmasını sağlar. Anahtar backend tarafında tutulmalı ve frontend koduna gömülmemelidir. Bazı provider'lar OAuth, workload identity veya farklı service credential yöntemleri sunabilir. Yetki mümkün olan en düşük kapsamda verilmelidir. Authentication hatası retry edilebilir transient problem gibi ele alınmamalıdır.

Model Seçimi

Model adı uygulamanın kalite, latency ve maliyet davranışını doğrudan etkiler. Aynı kullanım için büyük model yerine küçük model yeterli olabilir. Model ID configuration üzerinden seçilirse fallback veya A/B test daha kolay olur. Deprecated model hataları 404 veya provider-specific error biçiminde gelebilir. Production model version değişiklikleri regression test olmadan yapılmamalıdır.

Prompt ve Request Payload

Request payload prompt, messages, temperature, maximum output ve structured output ayarlarını içerebilir. Payload schema provider ve model sürümüne göre değişebilir. Uygulama request göndermeden önce gerekli alanları local validation'dan geçirmelidir. Çok büyük conversation history context length hatasına neden olabilir. Prompt boyutu aynı zamanda token maliyetinin önemli bölümünü oluşturur.

Response Yapısı

Response provider'ın teknik olarak başarılı kabul ettiği HTTP yanıtını içerir. Ancak HTTP 200 almak iş açısından kullanılabilir cevap aldığınız anlamına gelmez. Model boş content, geçersiz JSON veya eksik field döndürebilir. Bu nedenle response parsing sonrasında schema ve business validation uygulanmalıdır. Kullanılamayan 200 response uygulama seviyesi hata olarak ayrı sınıflandırılmalıdır.

Token Kullanımı ve Maliyet

Birçok AI API input ve output token hacmine göre maliyet üretir. Retry aynı prompt'un tekrar gönderilmesine yol açtığı için hata yönetimi doğrudan faturalandırmayı etkiler. Request başına input, output ve total token değerleri mümkünse kaydedilmelidir. Kullanıcı, departman veya feature bazında maliyet analizi yapılabilir. Fallback daha ucuz modele yönlendirildiğinde maliyet metriği bunun etkisini gösterebilir.

Timeout ve Request Configuration

Timeout tek bir sayıdan ibaret görülmemelidir. Connection timeout, read timeout ve workflow timeout ayrı ayarlanabilir. Çok kısa timeout başarılı olabilecek istekleri gereksiz tekrar ettirir. Çok uzun timeout ise provider problemi sırasında thread ve connection kaynaklarını tüketir. Gerçek P95 ve P99 latency ölçümü timeout değerlerinin belirlenmesinde kullanılmalıdır.

API Key ve Kimlik Bilgilerinin Güvenli Yönetimi

AI API entegrasyonunda en kritik güvenlik hatalarından biri credential'ların uygulama koduna veya frontend bundle içine yazılmasıdır. API key ele geçirildiğinde saldırgan provider kotanızı tüketebilir ve maliyet oluşturabilir. Secret management bu nedenle hata yönetiminden ayrı olmayan temel production gereksinimidir. Key rotation ve erişim sınırı incident etkisini azaltır. Log redaction ise hatayı araştırırken credential'ın başka sistemlere sızmasını engeller.

API Key Neden Frontend İçinde Tutulmamalı?

Browser veya mobil uygulama içinde bulunan secret kullanıcı tarafından çıkarılabilir. Obfuscation gerçek güvenlik sağlamaz. Frontend doğrudan provider'a bağlanırsa kullanıcı quota ve rate-limit policy'yi bypass edebilir. Backend gateway authentication ve kullanım kontrolü için merkezi nokta olmalıdır. Frontend yalnızca kurumun kendi güvenli API endpoint'ine bağlanmalıdır.

Environment Variable Kullanımı

Environment variable secret'ı source code'dan ayırmanın basit yollarından biridir. Development ve küçük servislerde kullanışlı olabilir. Ancak process environment debug çıktıları veya yanlış diagnostic log ile açığa çıkabilir. Deployment platformunun secret injection mekanizması tercih edilmelidir. Environment değerleri repository içinde .env dosyası olarak production credential ile saklanmamalıdır.

Secret Manager Yaklaşımı

Secret manager API key, certificate ve token'ları merkezi biçimde saklar. Uygulama runtime sırasında yetkili identity ile secret'a erişebilir. Erişim loglanabilir ve rotation kolaylaşır. Secret'ın deployment manifest içine düz metin yazılması gerekmez. Kurumsal AI API entegrasyonu ve hata yönetimi hizmeti planlanırken credential lifecycle temel mimari gereksinim olarak ele alınmalıdır.

API Key Rotation

API key düzenli veya olay bazlı olarak döndürülebilmelidir. Rotation sırasında kesinti yaşamamak için kısa süre eski ve yeni key birlikte desteklenebilir. Yeni key deployment'a alınır, bağlantı doğrulanır ve eski key iptal edilir. Key hangi servisler tarafından kullanılıyor inventory içinde bilinmelidir. Leak şüphesinde hızlı revoke mekanizması bulunmalıdır.

Yetki ve Erişim Sınırlandırması

Provider destekliyorsa API key yalnızca gerekli model, proje veya işlem kapsamıyla sınırlandırılmalıdır. Development credential production kaynağına erişmemelidir. Service account'lar kullanıcı hesaplarından ayrılmalıdır. Harcama limiti ve rate limit erişim kapsamına ek savunma sağlar. Least privilege hata veya key sızıntısının etkisini küçültür.

Loglara Hassas Veri Yazılmasını Önleme

HTTP client debug logları authorization header'ını yanlışlıkla kaydedebilir. Prompt içinde müşteri veya şirket verisi bulunabilir. Logging middleware header ve body alanlarında redaction uygulamalıdır. Error stack trace içinde request object'in tamamını yazdırmak risklidir. Observability için metadata yeterliyse tam prompt veya API key hiçbir zaman loglanmamalıdır.

AI API'lerinde En Sık Karşılaşılan Hatalar

AI API'lerinde HTTP status code hatanın ilk sınıflandırmasını sağlar ancak tek başına yeterli değildir. Aynı 429 kodu kısa süreli rate limit veya kalıcı quota problemi anlamına gelebilir. 500 ve 503 transient olabilirken 400 request'in düzeltilmesi gerektiğini gösterir. Uygulama provider-specific error body bilgisini normalize ederek ortak hata modeline dönüştürmelidir. Böylece retry, fallback ve kullanıcı mesajı hata türüne göre tutarlı uygulanabilir.

400 Bad Request

400 hatası istemcinin gönderdiği isteğin servis tarafından geçersiz bulunduğunu gösterir. Bu hata genellikle retry edilmemelidir çünkü aynı payload tekrar gönderildiğinde sonuç değişmez. Request schema ve parameter validation client tarafında mümkün olduğunca önceden yapılmalıdır. Error body kullanıcıya değil log ve diagnostic sistemine uygun biçimde kaydedilebilir. Production'da 400 oranının yükselmesi client release veya provider API değişikliğini gösterebilir.

Hatalı JSON veya Request Formatı

Eksik virgül, yanlış field tipi veya bozuk JSON request'in reddedilmesine neden olabilir. SDK kullanmak bu hataların bir bölümünü azaltır. Custom HTTP client'ta serialization testleri yapılmalıdır. Provider schema değişirse integration test problemi erken yakalayabilir. Aynı bozuk request'i retry etmek yalnızca latency ve maliyet üretir.

Geçersiz Parametreler

Model desteklemediği temperature, output format veya tool tanımı aldığında request geçersiz sayılabilir. Parameter validation model capability bilgisine göre yapılmalıdır. Provider-specific configuration abstraction katmanında yönetilebilir. Hata alındığında fallback model aynı parametreyi desteklemeyebilir. Routing öncesinde target model capability kontrolü yararlı olur.

Context Length / Token Limit Aşımı

Prompt ve conversation history model context limitini aştığında request reddedilebilir. Retry aynı payload ile yapılırsa sonuç değişmez. History trimming, summarization veya chunking uygulanmalıdır. Token estimation request öncesinde yapılabilir. Context hatası transient değil application-level input problemidir.

401 Unauthorized

401 genellikle eksik, hatalı veya süresi dolmuş credential anlamına gelir. Otomatik retry aynı key ile yapıldığında sorunu çözmez. Token refresh desteklenen authentication modelinde kontrollü yenileme uygulanabilir. API key rotation sırasında yanlış deployment bu hatayı artırabilir. Alarm üretilip credential configuration kontrol edilmelidir.

403 Forbidden

403 credential'ın geçerli ancak ilgili model veya kaynağa erişim yetkisinin olmadığını gösterebilir. Provider policy veya proje permission değişikliği nedeniyle ortaya çıkabilir. Retry çoğu durumda anlamlı değildir. Uygulama farklı model fallback yapacaksa yetkili alternatif model bulunup bulunmadığını kontrol edebilir. Yetki problemi security ve configuration incident olarak ele alınmalıdır.

404 Model veya Endpoint Bulunamadı

404 yanlış endpoint, model ID veya deprecated kaynak anlamına gelebilir. Network retry problemi çözmez. Configuration drift ve model version kontrol edilmelidir. Provider model adını değiştirdiyse compatibility mapping güncellenebilir. Production model listesi hard-coded yerine merkezi configuration ve test ile yönetilmelidir.

408 Request Timeout

408 server veya gateway isteğin belirlenen sürede tamamlanmadığını bildirebilir. İşlemin server tarafında gerçekten durup durmadığı bilinmeyebilir. Side effect üreten tool çağrılarında retry duplicate işlem riski taşır. Idempotency key kullanımı bu nedenle önemlidir. Read-only generation isteğinde kontrollü retry uygulanabilir.

429 Too Many Requests

429 rate limit veya kullanım kotasının aşıldığını gösterir. Yapay zeka API servislerinde 429 rate limit ve timeout hataları nasıl yönetilir sorusunun cevabı doğrudan tekrar yapmak değildir. Retry-After ve rate-limit header'ları varsa bunlara uyulmalıdır. Exponential backoff ve jitter client tarafındaki tekrar baskısını azaltır. Bakiye veya hard quota bittiğinde ise retry yapılmadan farklı aksiyon gerekir.

500 Internal Server Error

500 provider tarafındaki geçici iç hatayı gösterebilir. Kısa süreli transient sorunlarda retry mantıklı olabilir. Ancak aynı request sürekli 500 dönüyorsa sonsuz retry yapılmamalıdır. Retry budget ve circuit breaker devreye girmelidir. Error oranı provider outage sinyali olarak izlenmelidir.

502 Bad Gateway

502 ara gateway'in backend servisten geçerli yanıt alamadığını gösterir. AI provider altyapısında kısa süreli olabilir. Kontrollü retry çoğu durumda uygundur. Aynı anda çok sayıda istemcinin tekrar denemesi provider'ı daha fazla zorlayabileceği için jitter önemlidir. Sürekli 502 durumunda circuit breaker ve fallback devreye alınabilir.

503 Service Unavailable

503 servis geçici olarak kullanılamadığında yaygın status kodudur. Maintenance, kapasite veya provider outage kaynaklı olabilir. Retry-After varsa bekleme süresi dikkate alınmalıdır. Retry sayısı sınırlı tutulmalıdır. Uzun kesintide farklı provider, queue veya graceful degradation tercih edilmelidir.

504 Gateway Timeout

504 gateway'in backend'den zamanında yanıt alamadığını gösterir. İstek backend üzerinde hâlâ çalışıyor olabilir. Aynı isteğin yeniden gönderilmesi duplicate generation veya side effect yaratabilir. Idempotency ve request tracking önemlidir. Uzun generation işlemleri asenkron job mimarisine taşınabilir.

Network ve Connection Hataları

DNS çözümleme, TCP reset, TLS handshake veya bağlantı kopması HTTP status oluşmadan hata yaratabilir. Bunlar çoğu zaman transient olarak sınıflandırılabilir. Ancak configuration veya certificate problemi kalıcı olabilir. Retry sayısı düşük tutulup root cause metriği izlenmelidir. Network error oranı provider outage alarmından ayrı takip edilebilir.

Retry Edilebilir ve Retry Edilmemesi Gereken Hatalar

İyi hata yönetiminin temelinde retry kararını doğru vermek bulunur. Her hata için aynı retry politikası kullanmak production sistemlerinde en sık gördüğüm sorunlardan biridir. Transient hatalar zamanla düzelebilirken permanent hatalar aynı request tekrarlandığında değişmez. LLM API entegrasyonunda retry exponential backoff ve fallback stratejileri ancak bu sınıflandırma doğru yapılırsa etkili olur. Merkezi error classifier provider-specific kodları ortak retryable veya non-retryable sınıflara dönüştürmelidir.

Transient Hata Nedir?

Transient hata kısa süre sonra aynı isteğin başarılı olabileceği geçici problemdir. 503, bazı 500 hataları ve network reset buna örnek olabilir. Rate limit de bekleme sonrası geçici olabilir. Retry yapılırken server üzerindeki baskıyı artırmamak gerekir. Backoff ve jitter transient hataların temel kontrol mekanizmasıdır.

Permanent Hata Nedir?

Permanent hata request veya configuration değişmeden çözülmeyen problemdir. Hatalı model ID, geçersiz JSON veya yanlış API key buna örnektir. Aynı request'i tekrar göndermek yalnızca gecikme oluşturur. Kullanıcı veya operator düzeltmesi gerekir. Monitoring'de permanent error oranının artması deployment problemi gösterebilir.

Hangi HTTP Kodlarında Retry Yapılmalı?

Genellikle 429, 500, 502, 503 ve 504 kontrollü retry adayıdır. 408 ve network timeout idempotency durumuna göre retry edilebilir. Provider-specific error body daha ayrıntılı bilgi verebilir. Retry-After header varsa lokal backoff hesabının önüne geçebilir. Her provider için policy test edilip ortak error mapping içinde tutulmalıdır.

Hangi Hatalarda Retry Yapılmamalı?

400 sınıfındaki çoğu request hatası aynı payload ile tekrar edilmemelidir. Authentication veya permission problemi retry ile düzelmez. Context overflow önce input değişikliği gerektirir. Hard quota veya bakiye bitmesi durumunda beklemek yerine kullanıcıya veya operasyon ekibine farklı aksiyon sunulmalıdır. Non-retryable hata hızlı fail ederek gereksiz kaynak tüketimini azaltır.

Authentication Hataları

401 veya bazı 403 hataları credential veya yetki problemidir. Süresi dolmuş OAuth token varsa kontrollü refresh farklı bir işlemdir. Aynı invalid API key ile üç kez retry yapmak hiçbir fayda sağlamaz. Credential incident alarmı oluşturulmalıdır. Kullanıcıya servis geçici olarak kullanılamıyor gibi kontrollü mesaj verilebilir.

Geçersiz Request

Request schema yanlışsa payload düzeltilmeden retry yapılmamalıdır. Uygulama local validation ile bu hatayı provider'a ulaşmadan yakalayabilir. Geçersiz parameter telemetry olarak kaydedilmelidir. Yeni client release sonrası artış regression göstergesi olabilir. Retry budget bu tür hatalar için tüketilmemelidir.

Context Window Aşımı

Context window problemi request boyutuyla ilgilidir. Aynı conversation history yeniden gönderildiğinde yine başarısız olur. Uygulama geçmişi kısaltabilir veya özetleyebilir. Büyük doküman chunk'lara bölünebilir. Bu işlem retry değil request repair olarak sınıflandırılmalıdır.

Kota veya Bakiye Problemleri

429 her zaman kısa süreli rate limit değildir. Provider hesabının kredisi veya günlük kotası bittiyse beklemek tek başına çözüm olmayabilir. Error body ve header farkı analiz edilmelidir. Fallback provider veya kullanıcı bilgilendirmesi devreye girebilir. Budget alert bu hatanın production'da sürpriz olmasını önler.

Hata Sınıflandırma Katmanı Tasarlamak

Provider-specific exception'lar uygulamanın her yerine dağılmamalıdır. Merkezi classifier raw error'u RetryableRateLimit, AuthenticationError veya InvalidRequest gibi ortak tipe dönüştürebilir. Bu katman retry, fallback ve logging davranışının tek yerde belirlenmesini sağlar. Yeni provider eklendiğinde business logic değişmez. Error taxonomy observability dashboard'ları için de ortak dil oluşturur.

429 Rate Limit Hatasını Doğru Anlamak

Rate limit yalnızca saniyede çok fazla request göndermek anlamına gelmez. Provider requests per minute, tokens per minute ve concurrent request gibi birden fazla sınır uygulayabilir. Aynı request hacmi uzun prompt nedeniyle TPM limitine takılabilir. 429 yönetiminde header bilgilerini okumak ve client-side throttling uygulamak daha başarılı sonuç verir. Blind retry ise sistemin provider'a sürekli yük bindirmesine neden olur.

Requests Per Minute (RPM)

RPM belirli zaman aralığında yapılabilecek request sayısını sınırlar. Küçük ama çok sayıda chat request bu limite ulaşabilir. Client-side rate limiter request'leri dağıtarak burst etkisini azaltabilir. Queue yoğun saatlerde gelen işleri sıraya alabilir. Kullanıcı planı veya tenant bazında ayrı limit uygulanabilir.

Tokens Per Minute (TPM)

TPM input ve output token hacmine göre sınırlama uygular. Çok uzun context tek request olmasına rağmen yüksek token tüketebilir. Prompt trimming rate limit yönetimine doğrudan katkı sağlar. Queue scheduler tahmini token maliyetini dikkate alabilir. Token budget yalnızca maliyet değil kapasite kontrolüdür.

Concurrent Request Limitleri

Provider aynı anda açık request sayısını sınırlayabilir. Streaming bağlantılar uzun süre açık kaldığı için concurrency tüketimini artırır. Application connection pool ve worker count buna göre ayarlanmalıdır. Çok fazla parallel worker provider limitini aşabilir. Queue tabanlı concurrency semaphore kontrollü kullanım sağlar.

Kota veya Bakiye Tükenmesi

Hard quota rate limit'ten farklı davranış gerektirir. Bekleyip tekrar denemek günlük veya aylık limit sıfırlanana kadar işe yaramayabilir. Provider error code alt kategorisi ayrıştırılmalıdır. Budget alarm limit yaklaşmadan önce operasyon ekibini bilgilendirebilir. Alternatif provider veya feature degradation business continuity sağlayabilir.

Retry-After Header Nasıl Kullanılır?

Retry-After server'ın istemciye ne kadar beklemesi gerektiğini bildiren önemli header'dır. Varsa bu değer lokal retry delay hesabında öncelikli kullanılmalıdır. Birden fazla worker aynı süre sonunda aynı anda tekrar başlamasın diye küçük jitter eklenebilir. Header saniye veya tarih biçiminde gelebilir. HTTP client parser her iki formatı desteklemelidir.

Rate-Limit Header'larını Proaktif Takip Etmek

Bazı provider'lar kalan request veya token kapasitesini header içinde bildirir. Uygulama bu bilgiyi metriğe dönüştürebilir. Limit sıfıra yaklaşırken yeni işleri queue'ya almak 429 oluşmadan yükü azaltır. Header adları provider'a göre değişebilir. Abstraction layer bu farklılıkları ortak rate-limit state modeline çevirebilir.

Client-Side Rate Limiting

Client-side rate limiter request'i provider reddetmeden önce lokal olarak kontrol eder. Bu yaklaşım latency ve error rate'i azaltır. Multi-instance uygulamada dağıtık rate limiter gerekebilir. Redis gibi ortak state store kullanılabilir. Kullanıcı veya tenant bazlı limit global provider limitiyle birlikte uygulanabilir.

Token Bucket

Token bucket belirli hızda dolan kapasite havuzu yaklaşımıdır. Request geldiğinde bucket'tan token tüketilir. Kısa burst'lere izin verirken uzun dönem ortalama hızı sınırlar. Distributed sistemde atomic update gerekir. AI API çağrılarında request veya tahmini token maliyetine göre ağırlıklı bucket tasarlanabilir.

Sliding Window

Sliding window son belirli süre içindeki request sayısını takip eder. Sabit dakika sınırına göre boundary burst problemini azaltabilir. Daha doğru rate calculation karşılığında state maliyeti artar. Redis sorted set veya benzeri yapı kullanılabilir. Çok yüksek trafik sisteminde algoritmanın operasyon maliyeti de dikkate alınmalıdır.

Queue Tabanlı Throttling

Queue gelen request'leri doğrudan provider'a göndermek yerine kontrollü worker sayısıyla işler. Rate limit yaklaşırken worker hızı azaltılabilir. Kullanıcıya job status gösterilebilir. Interaktif chat için aşırı queue kullanıcı deneyimini bozabilir. Batch ve background işlemler için ise oldukça etkili yöntemdir.

Exponential Backoff ile Retry Stratejisi

Exponential backoff başarısız istekler arasında bekleme süresini kademeli artırır. İlk retry kısa bekler, sonraki denemeler daha uzun aralıklarla yapılır. Bu davranış provider outage sırasında aynı servise sürekli baskı göndermeyi azaltır. Jitter eklenmediğinde binlerce client aynı ritimde tekrar başlayabilir. Retry policy maksimum süre ve toplam bütçe ile sınırlandırılmalıdır.

Exponential Backoff Nedir?

Basit yaklaşımda bekleme süresi iki katına çıkarılabilir. Örneğin 0.5, 1, 2 ve 4 saniye gibi artış uygulanabilir. Gerçek production değerleri provider latency ve SLA'ya göre belirlenmelidir. Maximum backoff üst sınırı büyümeyi durdurur. Kullanıcı request'i için toplam bekleme süresi workflow timeout'u aşmamalıdır.

Neden Sabit Aralıklı Retry Yeterli Değildir?

Sabit bir saniyede tekrar denemek provider yoğunluğunun geçmesi için yeterli süre vermeyebilir. Bütün client'lar aynı sabit aralığı kullanırsa tekrar dalgası oluşur. Exponential backoff zamanla yükü seyrekleştirir. Uzun kesintide request sayısını ciddi biçimde azaltır. Bu yaklaşım hem provider hem uygulama kaynaklarını korur.

Jitter Nedir ve Neden Gereklidir?

Jitter bekleme süresine rastgelelik ekler. Aynı anda hata alan yüzlerce instance'ın aynı saniyede retry yapmasını önler. Full jitter veya equal jitter gibi farklı stratejiler kullanılabilir. Amaç synchronization kaynaklı retry storm'u azaltmaktır. Distributed AI istemcilerinde jitter kullanımı güçlü varsayılanlardan biridir.

Maksimum Retry Sayısı Nasıl Belirlenir?

Tek bir ideal retry sayısı yoktur. Interaktif kullanıcı request'i için düşük sayı tercih edilir çünkü kullanıcı dakikalarca beklememelidir. Background job daha fazla retry yapabilir. Hata türü ve provider SLA ayrıca dikkate alınmalıdır. Retry count yerine toplam elapsed retry time düşünmek çoğu zaman daha anlamlıdır.

Maximum Backoff Süresi Nasıl Belirlenir?

Backoff büyürken kullanıcı workflow'unun anlamını kaybetmemelidir. Chat request için 60 saniye beklemek kötü deneyim olabilir. Batch job için birkaç dakikalık bekleme kabul edilebilir. Provider Retry-After bilgisi üst sınır tasarımını etkileyebilir. Maximum backoff ve workflow timeout birlikte ayarlanmalıdır.

Retry Budget Nedir?

Retry budget sistemin toplam request hacminin ne kadarının tekrar çağrılara ayrılabileceğini belirler. Örneğin retry trafiğinin normal trafiğin belirli oranını aşmaması hedeflenebilir. Provider outage sırasında bütün worker'ların sürekli tekrar denemesini önler. Budget dolduğunda fail-fast veya fallback uygulanabilir. Bu yaklaşım sistem geneli güvenilirlik için önemlidir.

Retry Sonrası Fallback'e Ne Zaman Geçilmeli?

Transient hata birkaç kontrollü retry sonrasında devam ediyorsa fallback düşünülebilir. Ancak aynı provider içindeki alternatif model de aynı outage'dan etkileniyor olabilir. Provider health bilgisi routing kararına girdi olmalıdır. Fallback maliyet ve veri gizliliği açısından uygun değilse queue veya graceful degradation seçilebilir. Karar kullanıcı isteğinin kritikliğine göre verilmelidir.

Double Retry Problemi: SDK ve Uygulama Retry'larının Çakışması

Modern AI SDK'larının bir bölümü belirli hatalarda otomatik retry yapabilir. Uygulama geliştiricisi bunu bilmeden kendi retry wrapper'ını eklediğinde tek mantıksal istek birçok gerçek API çağrısına dönüşebilir. Bu durum latency ve token maliyetini beklenmedik biçimde artırır. Loglarda yalnızca dış retry sayısını görmek problemi gizleyebilir. Tek bir retry policy tasarlanmalı ve SDK behavior açık biçimde yapılandırılmalıdır.

AI SDK'larının Otomatik Retry Davranışı

SDK dokümantasyonunda hangi status code'ların kaç kez retry edildiği incelenmelidir. Varsayılan değerler version değişiminde farklılaşabilir. Request timeout da SDK tarafından ayrı yönetilebilir. Uygulama telemetry'si gerçek HTTP attempt sayısını kaydetmelidir. Wrapper seviyesindeki logical request ile network attempt ayrıştırılmalıdır.

Uygulama Katmanında Ek Retry Yapmanın Riski

SDK iki kez, uygulama wrapper'ı üç kez retry yaparsa teorik toplam attempt beklenenden çok daha yüksek olabilir. Nested retry backoff süreleri birleşerek kullanıcı latency'sini uzatır. Provider quota hızlı tüketilir. Side-effect request duplicate riskini artırır. Retry ownership tek katmanda açık biçimde tanımlanmalıdır.

Beklenmeyen İstek ve Maliyet Artışı

AI çağrıları token bazlı maliyet ürettiği için ekstra attempt doğrudan faturaya yansıyabilir. Provider bazı başarısız çağrılarda bile belirli compute veya token maliyeti hesaplayabilir. Retry rate dashboard bu artışı görünür yapmalıdır. Cost per logical request ile cost per HTTP attempt ayrı analiz edilebilir. Yüksek fark double retry veya kötü timeout politikasına işaret edebilir.

Tek Bir Retry Politikası Nasıl Tasarlanır?

Önce SDK retry kapatılabilir veya uygulama katmanı SDK davranışına uyumlu hale getirilebilir. Hangi hata sınıflarının retry edildiği tek configuration içinde tanımlanmalıdır. Backoff, jitter ve maximum elapsed time ortak policy olmalıdır. Logical request ID bütün attempt'lerde aynı tutulabilir. Böylece tracing ve maliyet analizi kolaylaşır.

Timeout Yönetimi

Timeout AI API entegrasyonunun kullanıcı deneyimini ve retry davranışını doğrudan belirler. Çok agresif timeout başarılı olabilecek uzun generation'ları keser. Çok geniş timeout provider outage sırasında thread ve connection tüketir. Connection, response ve workflow timeout ayrı seviyelerde ele alınmalıdır. Streaming için ilk token ve chunk aralığı ayrıca izlenmelidir.

Connection Timeout

Connection timeout istemcinin provider'a TCP veya TLS bağlantısı kurmak için ne kadar bekleyeceğini belirler. Genellikle generation süresinden çok daha kısa olmalıdır. DNS veya network problemi burada görünür hale gelir. Çok uzun connection timeout outage sırasında kaynakları kilitler. Retry bu seviyedeki transient hatalarda kontrollü uygulanabilir.

Read/Response Timeout

Read timeout bağlantı kurulduktan sonra veri bekleme süresini kontrol eder. Non-streaming uzun generation bu değeri aşabilir. Model ve prompt uzunluğuna göre gerçek latency ölçülmelidir. Provider'ın normal P99 süresinden çok düşük timeout gereksiz retry oluşturur. Uzun görevler mümkünse asynchronous flow'a taşınmalıdır.

Request-Level Timeout

Request-level timeout tek AI çağrısının toplam süresine üst sınır koyar. Connection ve read timeout'larını kapsayabilir. Retry attempt'lerinin her biri bu limite sahip olabilir. Ancak toplam logical request süresi ayrıca sınırlandırılmalıdır. Kullanıcı request'i sonsuz retry nedeniyle açık kalmamalıdır.

Workflow-Level Timeout

Bir AI workflow birden fazla model ve tool çağrısından oluşabilir. Her çağrı ayrı ayrı kısa olsa bile toplam süreç çok uzun sürebilir. Workflow deadline bütün zincire üst sınır koyar. Retry policy kalan süreyi dikkate almalıdır. Deadline dolduğunda partial result veya queue continuation gibi seçenekler değerlendirilebilir.

Streaming Timeout

Streaming bağlantısında tek read timeout kullanmak her zaman yeterli değildir. İlk token gelme süresi ile stream başladıktan sonra chunk'lar arası bekleme farklı anlam taşır. Uygulama iki metriği ayrı yönetebilir. Model ilk token üretmekte yavaş olabilir ancak başladıktan sonra düzenli akabilir. Stream ortasında sessizlik belirli sürenin üzerine çıkarsa connection failure kabul edilebilir.

İlk Token Süresi

Time to first token kullanıcı deneyiminde kritik metriktir. Provider queue yoğunluğu bu süreyi artırabilir. TTFT threshold aşıldığında kullanıcıya “işleniyor” durumu gösterilebilir. Hemen retry yapmak aynı yoğun provider'a ikinci yük bindirebilir. Routing layer alternatif healthy provider seçebilir.

Chunk'lar Arası Timeout

Stream başladıktan sonra her token aynı hızda gelmez. Bu nedenle çok kısa chunk timeout false failure üretir. P99 inter-chunk interval ölçülerek makul sınır seçilebilir. Uzun sessizlik provider veya network problemine işaret edebilir. Client partial response'u kullanıcıya nasıl göstereceğini önceden belirlemelidir.

Kopan Stream Nasıl Yönetilir?

Stream ortasında bağlantı koptuğunda response'un bir bölümü kullanıcıya ulaşmış olabilir. Aynı request'i baştan retry etmek duplicate text üretebilir. Uygulama partial content'i işaretleyip kullanıcıya yeniden oluştur seçeneği sunabilir. Provider resume özelliği destekliyorsa continuation token kullanılabilir. Resume yoksa yeni generation prompt'u mevcut partial content'i dikkate alacak şekilde tasarlanabilir.

Timeout Sonrası Retry Yapmanın Riskleri

Timeout istemcinin response'u almadığını gösterir, server'ın işi yapmadığını değil. Tool calling veya ödeme benzeri side effect varsa aynı request ikinci kez işlenebilir. Idempotency key bu riski azaltır. Generation çağrısında duplicate output maliyet oluşturabilir. Timeout retry kararı request'in idempotent olup olmadığına göre verilmelidir.

Idempotency: Aynı AI İsteğinin İki Kez Çalışmasını Önlemek

AI uygulamaları yalnızca metin üretmiyorsa idempotency kritik hale gelir. Model bir tool çağırıp veritabanına kayıt yazabilir veya harici işlem başlatabilir. Timeout sonrası retry aynı işlemi ikinci kez tetikleyebilir. Idempotency key logical request'i benzersiz biçimde tanımlar. Backend duplicate request'i yeni işlem başlatmadan önceki sonucuyla eşleştirebilir.

Idempotent Request Nedir?

Idempotent işlem aynı request birden fazla kez uygulandığında sistem durumunu bir kez uygulanmış gibi bırakır. Salt-okunur model generation teknik olarak state değiştirmeyebilir ancak maliyet ve kullanıcı sonucu yine çoğalır. Veritabanı yazan tool çağrısında idempotency daha kritik olur. Logical operation ID bütün retry attempt'lerinde aynı kalmalıdır. Yeni kullanıcı işlemi yeni key üretmelidir.

Retry Sonrası Duplicate İşlem Riski

İstemci timeout aldığında provider tool'u başarıyla çalıştırmış olabilir. Retry yeni bir tool call üretirse sipariş, ticket veya e-posta iki kez oluşturulabilir. Downstream service idempotency key'i saklayabilir. Aynı key tekrar geldiğinde mevcut result döndürülür. AI workflow side effect adımlarında bu koruma zorunlu kabul edilmelidir.

Idempotency Key Kullanımı

Key UUID veya request semantic identity üzerinden üretilebilir. Aynı kullanıcı aksiyonunun retry attempt'lerinde korunmalıdır. Key storage TTL iş sürecine göre belirlenir. Provider doğrudan idempotency destekliyorsa ilgili header kullanılabilir. Desteklemiyorsa uygulama veya tool gateway kendi dedup katmanını oluşturabilir.

Request ID ve Correlation ID

Request ID tek HTTP veya logical request'i tanımlayabilir. Correlation ID daha geniş workflow boyunca farklı servis çağrılarını birbirine bağlar. Retry attempt ID ayrıca tutulabilir. Logging bu kimlikleri response ve error kayıtlarına eklemelidir. Distributed tracing incident analizini ciddi biçimde kolaylaştırır.

Veritabanı Yazma veya Tool Calling İşlemlerinde Idempotency

Tool çağrısı input schema idempotency key alanını taşıyabilir. Veritabanında unique constraint duplicate işlemi engelleyebilir. External service key desteklemiyorsa local operation ledger tutulabilir. Modelin kendisine duplicate kontrol sorumluluğu verilmemelidir. Deterministic backend kontrolü her tool invocation'da uygulanmalıdır.

Circuit Breaker Pattern ile Zincirleme Hataları Önlemek

Circuit breaker sürekli hata veren provider'a request göndermeyi geçici olarak durdurur. Retry yalnızca tek request seviyesinde çalışırken circuit breaker sistem genelindeki sağlık durumunu korur. Provider outage sırasında binlerce yeni request'in her biri birkaç kez retry yaparsa hem latency hem maliyet büyür. Circuit breaker failure threshold sonrası open state'e geçerek hızlı fail sağlar. Belirli süre sonra half-open test request'leriyle recovery kontrol edilir.

Circuit Breaker Nedir?

Circuit breaker elektrik sigortasına benzer biçimde arızalı bağımlılığa giden trafiği keser. Servisin sürekli başarısız olduğunu gözlemlediğinde request'i provider'a göndermeden reddeder. Bu sayede connection pool ve worker kaynakları korunur. Kullanıcı daha hızlı fallback response alabilir. State ve metric merkezi veya instance bazında tasarlanabilir.

Closed State

Closed durumda request'ler normal biçimde provider'a gönderilir. Başarısız çağrılar failure counter'a eklenir. Belirlenen pencere içinde hata oranı threshold'u aşmazsa sistem closed kalır. Başarı oranı normal monitoring altında devam eder. Threshold aşılırsa open state'e geçilir.

Open State

Open durumda provider'a yeni request gönderilmez. Çağrı anında fallback, queue veya kontrollü hata ile sonuçlanır. Belirli cooldown süresi boyunca sistem recovery denemesi yapmaz. Bu davranış provider'a toparlanma alanı sağlar. Cooldown sonunda half-open state'e geçilebilir.

Half-Open State

Half-open durumunda sınırlı sayıda test request provider'a gönderilir. Başarılı sonuçlar circuit'in tekrar closed olmasını sağlayabilir. Hata devam ederse circuit yeniden open olur. Test request sayısı düşük tutulmalıdır. Aynı anda bütün instance'ların recovery testi göndermesi engellenebilir.

Failure Threshold Nasıl Belirlenir?

Tek bir başarısız request circuit'i açmamalıdır. Belirli zaman penceresinde error rate veya art arda hata sayısı kullanılabilir. Trafik hacmi düşük sistemlerde yüzde metriği yanıltıcı olabilir. Minimum request count tanımlanmalıdır. 500, 502, 503 ve network error gibi transient provider failure'lar breaker hesabına dahil edilebilir.

Circuit Breaker ve Retry Birlikte Nasıl Kullanılır?

Request önce circuit breaker durumunu kontrol eder. Closed ise sınırlı retry policy ile provider çağrılır. Tek logical request'in retry'ları başarısız olduğunda failure metriği breaker'a bildirilir. Circuit açıldığında yeni request'ler retry yapmadan fallback'e gider. Bu sıra retry storm'u ciddi biçimde azaltır.

Fallback Stratejileri

Fallback bir AI servisi başarısız olduğunda uygulamanın tamamen kullanılamaz hale gelmesini önler. Alternatif model, provider, cache, static response veya insan incelemesi farklı fallback türleridir. En iyi seçenek kullanım senaryosu ve veri hassasiyetine göre değişir. Provider değiştirmek teknik olarak kolay olsa da veri gizliliği ve model davranışı açısından önemli sonuçlar doğurabilir. Fallback sonucu kalite ve maliyet monitoring altında ayrıca izlenmelidir.

Aynı Provider İçinde Alternatif Model

Ana model geçici olarak unavailable olduğunda aynı provider içindeki başka model kullanılabilir. Authentication ve network aynı kaldığı için entegrasyon basittir. Ancak provider genel outage yaşıyorsa alternatif model de çalışmayabilir. Output kalite ve schema compatibility önceden test edilmelidir. Fallback model adı response metadata'sına kaydedilebilir.

Daha Hızlı veya Daha Küçük Modele Geçiş

Yoğunluk veya latency problemi sırasında daha küçük model tercih edilebilir. Kullanıcıya daha kısa veya daha sınırlı yanıt sunulabilir. Kritik reasoning görevlerinde kalite düşüşü kabul edilmeyebilir. Routing policy hangi use case'in küçük modele geçebileceğini belirlemelidir. Cost ve latency kazanımı ayrı metric olarak izlenebilir.

Alternatif AI Provider Kullanımı

Farklı provider'a geçiş yüksek availability sağlayabilir. Bunun için request ve response abstraction önceden tasarlanmalıdır. Tool calling, structured output ve model parametreleri birebir aynı olmayabilir. Provider data policy ve bölgesel processing koşulları değerlendirilmelidir. Fallback yalnızca teknik availability değil compliance açısından da onaylanmalıdır.

OpenAI → Anthropic → Gemini Benzeri Provider Zincirleri

Birden fazla provider zinciri tasarlanabilir ve belirli sağlık durumuna göre sırayla denenebilir. Buradaki marka sırası örnek mimariyi anlatır, kalite sıralaması anlamına gelmez. Her provider için ortak input ve normalized output adapter gerekir. Aynı prompt farklı model ailesinde farklı davranabilir ve regression test zorunludur. Veri gizliliği ile contractual koşullar provider değişmeden önce doğrulanmalıdır.

Cache Fallback

Aynı veya benzer request daha önce başarıyla cevaplandıysa cached response kullanılabilir. FAQ, sabit bilgi veya deterministic extraction görevlerinde faydalıdır. Kullanıcıya eski veri gösterme riski varsa TTL uygulanmalıdır. Cache key model version ve prompt template'i içermelidir. Hassas kullanıcı verisi cross-user cache içinde paylaşılmamalıdır.

Static Response Fallback

AI özelliği kritik değilse kontrollü sabit mesaj en güvenli fallback olabilir. Örneğin “Bu özellik geçici olarak kullanılamıyor” mesajı yanlış model çıktısından daha iyidir. Kullanıcıya tekrar deneme veya alternatif işlem yolu sunulabilir. Static response incident sırasında sistemin ana işlevini korur. Her feature için graceful degradation mesajı önceden hazırlanmalıdır.

Queue ve Daha Sonra İşleme

Acil olmayan işler provider düzelene kadar queue'da bekletilebilir. Kullanıcıya job kabul edildi bilgisi verilir. Circuit kapanınca worker işlemleri devam ettirir. Queue retention ve expiry belirlenmelidir. Güncelliğini kaybeden job otomatik iptal edilebilir.

Human-in-the-Loop Fallback

Yüksek etkili süreçte AI başarısız olduğunda insan incelemesine geçilebilir. Ticket oluşturulup ilgili ekip bilgilendirilebilir. Kullanıcı tamamen sonuçsuz bırakılmaz. İnsan kapasitesi sınırlı olduğu için yalnızca kritik use case'lerde uygulanmalıdır. Fallback oranı yükselirse provider veya model reliability problemi araştırılmalıdır.

Multi-Provider AI Mimarisi

Multi-provider mimari uygulamanın tek model sağlayıcısına sıkı bağımlılığını azaltır. Ancak iki SDK'yı aynı projeye eklemek gerçek abstraction oluşturmaz. Request, response, error, metric ve privacy davranışı ortak model altında yönetilmelidir. Akıllı routing availability, latency, maliyet ve kalite kriterlerini dikkate alabilir. Provider değişiminde veri işleme şartlarının aynı olmadığı unutulmamalıdır.

Vendor Lock-in Problemi

Uygulamanın business logic'i provider'a özel response objesine bağlıysa provider değişimi pahalı hale gelir. Tool calling formatı ve parameter isimleri kodun her yerine yayılmamalıdır. Internal AI client interface provider ayrıntılarını gizleyebilir. Ancak en düşük ortak özellik setine düşmek de gelişmiş özellikleri kaybettirebilir. Abstraction ortak çekirdek ve provider-specific extension birlikte destekleyebilir.

Provider Abstraction Layer

Abstraction layer sendChat, generateStructured veya createEmbedding gibi ortak operasyonlar tanımlayabilir. Her provider adapter bu interface'i uygular. Retry ve timeout ortak policy ile yönetilebilir. Provider-specific exception normalized error tipine çevrilir. Business service hangi SDK kullanıldığını bilmek zorunda kalmaz.

Ortak Request/Response Modeli

Internal request modeli messages, model role, max tokens ve tool definitions gibi alanları ortaklaştırabilir. Adapter gerekli dönüşümü provider formatına yapar. Response content, usage ve finish reason ortak schema'ya çevrilir. Desteklenmeyen özellik capability flag ile belirtilir. Bu yapı test ve fallback kodunu sadeleştirir.

Provider'a Özgü Hataları Normalize Etmek

Her provider farklı exception class ve error code kullanabilir. Normalization katmanı bunları RateLimited, Unavailable, InvalidRequest ve Authentication gibi ortak sınıflara dönüştürür. Retry policy bu ortak tiplere göre çalışır. Raw provider code diagnostic metadata olarak korunabilir. Dashboard provider bağımsız error type üzerinden rapor üretir.

Provider Health Check

Health yalnızca homepage veya TCP erişimiyle ölçülmemelidir. Küçük gerçek inference probe sınırlı aralıkla kullanılabilir. Maliyet nedeniyle çok sık yapılmamalıdır. Production request error rate de health score'a dahil edilebilir. Routing layer provider durumunu cached health state üzerinden kullanabilir.

Akıllı Routing

Routing sadece sıradaki provider'ı seçmekten daha gelişmiş olabilir. Availability, latency, maliyet ve kalite birlikte score edilebilir. User veya feature policy bazı provider'ları dışlayabilir. Routing kararının nedeni loglanmalıdır. A/B veya canary dağılımı aynı altyapı üzerinden yönetilebilir.

Availability Bazlı Routing

Provider circuit open durumundaysa yeni trafik başka provider'a yönlendirilebilir. Health score minimum threshold altında ise routing dışı bırakılabilir. Recovery sonrası düşük yüzde trafikle tekrar denenebilir. Ani provider değişimi bütün trafiği alternatif servise yığmamalıdır. Alternatif provider'ın kapasitesi de dikkate alınmalıdır.

Maliyet Bazlı Routing

Basit görevler daha düşük maliyetli modele yönlendirilebilir. Kullanıcı premium feature kullanıyorsa daha güçlü model seçilebilir. Token tahmini routing öncesi yapılabilir. Maliyet tek kriter olmamalıdır çünkü düşük kalite tekrar request yaratabilir. Request başına gerçek cost metriği policy optimizasyonunda kullanılmalıdır.

Latency Bazlı Routing

Provider P95 latency değerleri zaman içinde karşılaştırılabilir. Interaktif chat düşük latency modeline yönlendirilebilir. Batch iş kalite veya maliyet odaklı farklı provider kullanabilir. Bölgesel network gecikmesi de routing kararını etkileyebilir. Geçici latency spike circuit açmadan routing weight düşürmek için kullanılabilir.

Model Kalitesi Bazlı Routing

Her görev için aynı model en iyi sonucu vermeyebilir. Kodlama, extraction veya Türkçe metin için farklı benchmark sonuçları olabilir. Task classifier uygun model ailesini seçebilir. Quality score düzenli evaluation dataset ile güncellenmelidir. Kullanıcı talebi yüksek riskli ise fallback kalite sınırı daha sıkı tutulabilir.

Provider Değiştirirken Veri Gizliliği

Bir request'i farklı provider'a göndermek veri işleme lokasyonu ve sözleşme koşullarını değiştirebilir. Hassas data için allowlist uygulanmalıdır. Bazı tenant'lar yalnızca belirli provider üzerinden işlem görebilir. Routing engine compliance policy'yi teknik constraint olarak uygulamalıdır. Fallback availability uğruna gizlilik politikasını ihlal etmemelidir.

Graceful Degradation: AI Servisi Çöktüğünde Uygulamayı Çalışır Tutmak

AI özelliğinin çalışmaması bütün ürünün kullanılamaz hale gelmesini gerektirmez. Graceful degradation kullanıcıya daha sınırlı ama çalışan deneyim sunar. AI özelliği destekleyici ise geçici olarak kaldırılabilir. Cached veya static response kullanılabilir. Uygulamanın temel işlevi provider outage'dan mümkün olduğunca bağımsız kalmalıdır.

Tam Özellikten Kısıtlı Özelliğe Geçiş

Örneğin gelişmiş rapor üretimi unavailable olduğunda yalnızca temel özet sunulabilir. Kullanıcı hangi özelliğin geçici olarak sınırlı olduğunu bilmelidir. Feature flag hızlı geçiş sağlar. Kısıtlı mod önceden test edilmelidir. Incident sırasında ilk kez yazılmaya çalışılan fallback güvenilir olmaz.

Cached Response Kullanımı

Sık sorulan ve değişmeyen içerikler cache'den sunulabilir. Cache freshness kullanıcıya göre önemli olabilir. Kişiselleştirilmiş cevap cross-user kullanılmamalıdır. Provider döndüğünde cache normal stratejiye geri döner. Cache hit ve stale serve oranı monitoring altında tutulabilir.

Daha Basit Model Kullanımı

Büyük model unavailable olduğunda daha küçük model temel işlevi koruyabilir. Response style ve schema compatibility test edilmelidir. Kullanıcıya kalite düşüşünü her zaman teknik terimlerle açıklamak gerekmez. Kritik karar use case'inde daha basit model kabul edilmeyebilir. Feature policy uygun fallback seviyesini belirlemelidir.

AI Özelliğini Geçici Olarak Devre Dışı Bırakmak

Bazen en güvenli çözüm özelliği kapatmaktır. Yanlış veya düşük kaliteli cevap vermek kullanıcıya daha fazla zarar verebilir. Feature flag operasyon ekibine hızlı kontrol sağlar. UI alternatif manuel yolu gösterebilir. Devre dışı bırakma incident runbook içinde belgelenmelidir.

Kullanıcıya Anlamlı Hata Mesajı Sunmak

“500 Internal Server Error” son kullanıcıya yardımcı olmaz. Mesaj ne olduğunu teknik ayrıntıya boğmadan açıklamalıdır. Kullanıcı tekrar deneyebilir, işi kaydedebilir veya alternatif işlem kullanabilir. Request ID destek ekibine sorun bildirmek için gösterilebilir. Provider adı veya internal stack trace kullanıcıya açılmamalıdır.

AI'ya Özgü Uygulama Seviyesi Hatalar

AI servislerinde bütün başarısızlıklar HTTP hata kodu üretmez. Provider 200 döndürürken model geçersiz JSON, eksik alan veya mantıksız sonuç verebilir. Bu durum klasik API entegrasyonundan önemli bir farktır. Response validation ve business rule kontrolü zorunlu hale gelir. Hallucination ve tool calling hataları ayrı error taxonomy altında ele alınmalıdır.

Context Length Exceeded

Conversation büyüdükçe input token sayısı model sınırını aşabilir. Uygulama kullanıcıya teknik hata vermek yerine geçmişi yönetmelidir. Son mesajlar korunup eski bölümler özetlenebilir. Büyük doküman retrieval veya chunking ile seçilebilir. Context budget her request öncesinde hesaplanabilir.

Conversation History Kısaltma

En eski mesajları kaldırmak en basit yöntemdir. Ancak eski kritik talimat kaybolabilir. System message ve önemli user preferences ayrı tutulmalıdır. Sliding conversation window uygulanabilir. Hangi mesajların çıkarıldığı observability amacıyla metadata olarak kaydedilebilir.

Summarization

Eski conversation bölümü ayrı model çağrısıyla özetlenebilir. Özet yeni context'te tek message olarak kullanılır. Bu yaklaşım token maliyetini azaltır ancak ek model çağrısı gerektirir. Özet hatası sonraki konuşmayı etkileyebilir. Structured memory yaklaşımı kritik bilgilerin kaybolmasını azaltabilir.

Chunking

Büyük input bağımsız parçalara bölünebilir. Her chunk ayrı işlenip sonuçlar birleştirilebilir. Summarization ve document extraction görevlerinde yaygındır. Chunk sınırı anlamlı bölüm yapısını korumalıdır. Final aggregation tekrar token limiti oluşturmamalıdır.

Content Filter ve Moderation Hataları

Provider request veya response'u policy nedeniyle engelleyebilir. Bu durum normal server error gibi retry edilmemelidir. Kullanıcı prompt'u yeniden formüle edebiliyorsa açıklayıcı mesaj gösterilebilir. False positive moderation vakaları ayrı izlenmelidir. Fallback provider kullanmak policy bypass amacıyla yapılmamalıdır.

Geçersiz veya Eksik JSON Çıktısı

Model JSON istediğiniz halde markdown veya eksik kapanan object döndürebilir. JSON parse hatası application-level failure'dır. Structured output veya schema constrained generation destekleniyorsa kullanılmalıdır. Parse başarısızsa kontrollü repair veya sınırlı retry uygulanabilir. Raw output gizlilik kurallarına uygun biçimde diagnostic olarak saklanabilir.

Schema Validation Hataları

JSON syntactically geçerli olabilir ama beklenen field veya type bulunmayabilir. JSON Schema veya typed model validation kullanılmalıdır. Missing optional field default değerle tamamlanabilir. Kritik field eksikse response başarısız kabul edilmelidir. Retry aynı prompt'la yapılacaksa repair instruction eklemek daha anlamlı olabilir.

Hallucination ve Mantıksal Hatalar

Model fluent ama yanlış bilgi üretebilir. Bu hata HTTP katmanında görünmez. RAG citation validation veya deterministic business checks kullanılabilir. Yüksek riskli output insan review gerektirebilir. Hallucination rate ayrı evaluation ve monitoring yaklaşımı ister.

Tool / Function Calling Hataları

Model olmayan tool seçebilir veya argument schema'sını yanlış doldurabilir. Backend her tool çağrısını validation'dan geçirmelidir. Permission kontrolü model kararına bırakılmamalıdır. Tool error modele kontrollü şekilde geri verilerek yeniden planlama yapılabilir. Aynı side effect tool tekrar çalıştırılırken idempotency korunmalıdır.

HTTP 200 Döndüğü Halde Response'un Kullanılamaz Olması

Bu durum AI entegrasyonlarında özellikle sık görülür. Network katmanı başarılıdır ama business contract karşılanmaz. Application error class HTTP status'tan bağımsız tanımlanmalıdır. Success rate metriği yalnızca HTTP 2xx üzerinden hesaplanmamalıdır. Validated success ayrı metric olarak izlenmelidir.

Structured Output ve Response Validation

AI model çıktısına doğrudan veritabanı veya business action girdisi olarak güvenmek risklidir. Model çıktısı probabilistic olduğu için format ve içerik değişebilir. JSON Schema, type validation ve business rule katmanları response'u güvenli hale getirir. Validation başarısızsa blind retry yerine hata türüne göre repair veya fallback yapılmalıdır. Structured output production AI entegrasyonunda temel kontrat olarak görülmelidir.

AI Çıktısına Neden Doğrudan Güvenilmemeli?

Model “yalnızca JSON döndür” talimatını her zaman kusursuz uygulamayabilir. Field değeri yanlış type olabilir. Business açısından imkansız tarih veya miktar üretilebilir. Prompt injection output schema'yı bozabilir. Uygulama bütün dış girdiler gibi AI response'u da untrusted input olarak ele almalıdır.

JSON Schema ile Doğrulama

JSON Schema gerekli alanları, type ve allowed value'ları tanımlar. Response parse edildikten sonra validator çalıştırılır. Provider native structured output sunuyorsa başarı oranı yükselir. Yine de application validation kaldırılmamalıdır. Schema version değişikliği client compatibility ile birlikte yönetilmelidir.

Type Validation

Typed language veya runtime validation library response contract'ını kod seviyesinde korur. String beklenen alanda number gelirse hata erken yakalanır. Nullable ve optional field'lar açık biçimde tanımlanmalıdır. Type coercion kritik alanlarda dikkatle kullanılmalıdır. Silent conversion hatalı business decision oluşturabilir.

Eksik Alanların Yönetimi

Her eksik field aynı severity'ye sahip değildir. Opsiyonel açıklama boş olabilirken işlem tutarı eksikse response kullanılamaz. Schema criticality bilgisi taşıyabilir. Default value yalnızca anlamlı olduğu durumda kullanılmalıdır. Eksik alan oranı model kalite metriği olarak izlenebilir.

Validation Başarısızsa Retry Yapılmalı mı?

Bazen model ikinci denemede doğru format üretebilir. Ancak sınırsız retry aynı hatalı prompt'u tekrar eder. İlk failure sonrası explicit repair instruction eklenebilir. İkinci başarısızlıkta fallback model veya human review tercih edilebilir. Retry count ve ek token maliyeti izlenmelidir.

Self-Repair ve Output Correction Stratejileri

Geçersiz output ikinci modele veya aynı modele “bu schema'ya düzelt” talimatıyla gönderilebilir. Bu işlem yeni AI çağrısı olduğu için maliyet ve latency ekler. Deterministic JSON fixer basit syntax hatalarında daha ucuz olabilir. Kritik semantic field'lar yalnızca format repair ile güvenilir hale gelmez. Repair sonrası tekrar validation zorunludur.

Streaming AI API'lerinde Hata Yönetimi

Streaming kullanıcı deneyimini iyileştirir ancak hata yönetimini daha stateful hale getirir. Stream başlamadan önceki 429 ile ortada kopan connection aynı şekilde ele alınamaz. Partial response kullanıcıya gösterilmiş olabilir. Retry UI ve backend coordination gerektirir. Client disconnect olduğunda gereksiz provider generation'ı mümkünse iptal edilmelidir.

Stream Başlamadan Önce Oluşan Hatalar

İlk byte gelmeden oluşan hata klasik API hatasına benzer yönetilebilir. 429, 503 veya authentication error normal classifier'a gider. Retry policy henüz kullanıcıya content gösterilmediği için daha basittir. Timeout TTFT seviyesinde ölçülebilir. Fallback başka provider'a geçebilir.

Stream Ortasında Bağlantının Kopması

Kullanıcı yanıtın bir bölümünü gördükten sonra stream kesilebilir. Backend partial buffer tutuyorsa mevcut metin korunabilir. Retry tamamen yeni response üretebilir ve önceki bölümle uyuşmayabilir. Resume destekleniyorsa devam mekanizması kullanılmalıdır. Desteklenmiyorsa UI kullanıcıya yeniden oluşturma seçeneği sunabilir.

Partial Response Yönetimi

Partial response final business output olarak işlenmemelidir. Chat UI içinde “yanıt tamamlanamadı” işaretiyle gösterilebilir. Structured generation'da yarım JSON kesinlikle parse edilmemelidir. Audit log response_complete boolean bilgisi taşıyabilir. User retry aynı logical conversation context ile yapılabilir.

Kullanıcı Arayüzünde Retry

Kullanıcı retry butonuna bastığında backend yeni logical attempt başlatabilir. Aynı idempotency key side-effect işlemde korunmalıdır. Chat generation için yeni request ID üretilebilir ama parent correlation ID aynı kalabilir. UI duplicate response eklememelidir. Retry sayısı kullanıcıya teknik olarak gösterilmese bile monitoring'e kaydedilmelidir.

Resume veya Yeniden Başlatma Stratejileri

Bazı protokoller continuation token veya cursor sunabilir. Böyle destek yoksa response yeniden üretilebilir. Prompt'a mevcut partial text eklemek continuation kalitesini artırabilir ama model tekrar eden bölüm üretebilir. Duplicate suffix temizliği dikkatle yapılmalıdır. Kritik structured task baştan üretmek daha güvenli olabilir.

Client Disconnect Yönetimi

Kullanıcı browser'ı kapattığında backend request'in devam edip etmediğini bilmelidir. Generation sonucu başka amaçla kullanılmayacaksa provider request iptal edilebilir. Cancellation token veya abort signal kullanılabilir. Provider cancellation desteklemiyorsa maliyet devam edebilir. Disconnect rate ve wasted token metric izlenebilir.

Asenkron AI İşleri ve Queue Kullanımı

Uzun AI görevlerini request-response bağlantısında tutmak production güvenilirliğini azaltabilir. Queue işi dayanıklı job'a dönüştürür. Worker kontrollü concurrency ve rate limit ile provider'ı tüketir. Failed job retry ve dead letter queue süreçleri hata yönetimini standardize eder. Kullanıcı job status veya webhook üzerinden sonuç alabilir.

Hangi AI İşleri Queue'ya Alınmalı?

Büyük belge özetleme, toplu classification ve uzun rapor üretimi iyi queue adaylarıdır. Kullanıcının saniyeler içinde sonucu görmesi gerekmiyorsa asenkron iş daha güvenlidir. High-volume embedding generation da worker tabanlı çalışabilir. Çok kısa chat isteklerini queue'ya almak gereksiz latency yaratabilir. Karar SLA ve işlem süresine göre verilmelidir.

Worker Tabanlı AI API Tüketimi

Worker queue'dan job alır ve AI client üzerinden provider çağrısı yapar. Concurrency worker sayısıyla kontrol edilir. Rate limiter ortak state kullanabilir. Job heartbeat uzun işlemlerde worker'ın canlı olduğunu gösterir. Sonuç database veya object storage'a yazılır.

Failed Job Retry

Transient provider hatasında job belirli delay ile yeniden queue'ya alınabilir. Retry count job metadata içinde tutulur. Permanent error doğrudan failed state'e geçer. Retry budget queue sisteminde de uygulanmalıdır. Aynı job sonsuz döngüye girmemelidir.

Dead Letter Queue

Belirlenen retry limitini aşan işler DLQ'ya taşınır. Operasyon ekibi problemli job'ları ayrı inceleyebilir. PII içeren payload varsa DLQ access sınırlandırılmalıdır. Manual replay kontrollü yapılmalıdır. Root cause düzeltildikten sonra batch reprocess uygulanabilir.

Job Status Takibi

Queued, running, completed ve failed gibi durumlar kullanıcıya gösterilebilir. Progress yüzdesi AI generation için her zaman doğru tahmin edilemeyebilir. Status endpoint polling veya websocket ile sunulabilir. Job ID kullanıcı yetkisine bağlı olmalıdır. Başka kullanıcının job sonucu ID tahminiyle erişilememelidir.

Webhook ile Sonuç Bildirimi

Asenkron entegrasyonda sonuç webhook ile başka sisteme gönderilebilir. Webhook signature doğrulaması yapılmalıdır. Delivery failure için ayrı retry policy gerekir. Webhook receiver idempotent olmalıdır. Aynı completion event birden fazla kez ulaşabilir.

Logging ve Observability

AI API kullanımında observability olmadan hata yönetiminin gerçekten çalışıp çalışmadığını bilmek zordur. Her logical request için provider, model, latency, token ve retry bilgisi izlenmelidir. Prompt ve response'un tamamını loglamak çoğu zaman gerekli değildir. Distributed tracing çok servisli workflow'da request'in nerede geciktiğini gösterir. AI API kullanımında circuit breaker kuyruk yönetimi ve hata loglama yöntemleri aynı correlation ID üzerinden bağlandığında incident analizi ciddi biçimde hızlanır.

Her API İsteğinde Neler Loglanmalı?

Log tasarımı debugging ve gizlilik arasında denge kurmalıdır. Request ID, provider ve model temel metadata'dır. Latency, retry ve HTTP status operasyon davranışını gösterir. Token ve cost maliyet analizini sağlar. Error type normalized taxonomy üzerinden yazılmalıdır.

Request ID

Request ID her logical çağrıyı benzersiz tanımlar. Kullanıcı hata mesajında support reference olarak gösterilebilir. Retry attempt'leri parent request ID ile ilişkilendirilebilir. Log search hızlı hale gelir. ID kişisel veri içermemelidir.

Model

Model adı performance ve error davranışını karşılaştırmak için gerekir. Model version değişimi metric trendini etkiler. Fallback kullanıldığında original ve final model ayrı kaydedilebilir. Deprecated model hataları kolay bulunur. Model ID tek başına prompt içeriğini ifşa etmez.

Provider

Provider bilgisi multi-provider sistemde incident source'u gösterir. Fallback rate provider bazında analiz edilebilir. Latency karşılaştırması yapılabilir. Contractual maliyet dashboard'una katkı sağlar. Provider adı kullanıcıya doğrudan gösterilmek zorunda değildir.

Latency

End-to-end ve provider latency mümkünse ayrı tutulmalıdır. Queue wait ayrıca ölçülebilir. P50, P95 ve P99 hesaplanır. Timeout threshold buna göre ayarlanır. Retry toplam logical latency'yi etkiler.

Token Kullanımı

Input ve output token ayrı kaydedilmelidir. Retry nedeniyle toplam token artışı görülebilir. Prompt optimization etkisi ölçülebilir. Kullanıcı veya feature bazlı aggregate rapor üretilebilir. Hassas text tutulmadan maliyet görünürlüğü sağlanır.

Retry Sayısı

Retry count güvenilirlik sorununu gösterir. Yüksek sayı provider instability veya kötü timeout policy'ye işaret edebilir. SDK internal attempts mümkünse dahil edilmelidir. Logical ve network retry ayrılabilir. Cost metriğiyle birlikte yorumlanmalıdır.

HTTP Status

HTTP status temel hata dağılımını gösterir. 429 artışı rate-limit tuning ihtiyacını gösterir. 5xx provider health sinyalidir. 400 artışı client regression olabilir. HTTP 200 validated success anlamına gelmediği için application status ayrıca tutulmalıdır.

Error Type

Normalized error type dashboard ve alert kurallarını sadeleştirir. RateLimited, Timeout, InvalidResponse veya Authentication gibi sınıflar kullanılabilir. Raw provider error code ayrı metadata'da tutulabilir. Kullanıcıya gösterilen hata mesajı bu sınıftan türetilebilir. Error taxonomy versionlanabilir.

Prompt ve Kullanıcı Verisini Loglamanın Riskleri

Prompt şirket sırrı, kişisel veri veya müşteri bilgisi içerebilir. Full body log merkezi log platformunda yeni hassas veri kopyası oluşturur. Metadata-only logging güçlü varsayılandır. Debug gerektiğinde sınırlı sample ve redaction uygulanabilir. Retention ve erişim policy açık biçimde belirlenmelidir.

Distributed Tracing

Bir AI request auth service, queue, provider ve database üzerinden geçebilir. Trace span her aşamanın süresini gösterir. Provider HTTP call ayrı span olarak işaretlenebilir. Retry attempt'leri child span şeklinde görünür. Böylece yavaşlığın AI modelinden mi uygulama katmanından mı geldiği anlaşılır.

Correlation ID ile İstek Takibi

Correlation ID microservice zincirinin tamamında korunmalıdır. Worker job farklı process'te çalışsa bile aynı correlation ID devam ettirilebilir. Webhook event bu ID'yi taşıyabilir. Incident sırasında tek arama bütün workflow loglarını getirir. User ID yerine correlation ID paylaşmak gizlilik açısından daha güvenlidir.

AI API Monitoring için Takip Edilmesi Gereken Metrikler

Monitoring yalnızca uptime ölçmemelidir. Validated success rate, latency, retry, fallback ve token maliyeti AI servisinin gerçek sağlığını gösterir. Streaming sistemlerde time to first token ayrıca kritik metriktir. Circuit breaker activation provider instability sinyali verir. Request başına maliyet güvenilirlik politikalarının finansal etkisini görünür hale getirir.

Success Rate

Success rate yalnızca 2xx response oranı olmamalıdır. Response validation başarılı olmalıdır. Structured output parse failure başarısız kabul edilmelidir. Model veya provider bazında ayrı raporlanabilir. Kullanıcı feature SLA'sı validated success üzerinden tanımlanabilir.

Error Rate

Error rate normalized error category bazında izlenmelidir. 429 ve 5xx aynı incident tipi değildir. Client 4xx artışı deployment regression gösterebilir. Zaman penceresi ve minimum request hacmi alert tasarımında kullanılmalıdır. Per-provider oran multi-provider health kararını besler.

P50, P95 ve P99 Latency

P50 normal request davranışını gösterir. P95 yoğun veya daha yavaş kullanıcı deneyimini temsil eder. P99 tail latency problemine ışık tutar. Ortalama değer outlier'ları gizleyebilir. Timeout ve routing kararında percentile metric'ler daha faydalıdır.

Time to First Token

TTFT streaming kullanıcı deneyiminin temel göstergesidir. Queue, provider ve prompt processing süresini etkiler. P95 TTFT artışı kapasite veya provider sorunu gösterebilir. İlk token hızlı gelip toplam generation yavaş olabilir. TTFT ve total latency birlikte izlenmelidir.

Retry Rate

Retry rate logical request'lerin ne kadarının tekrar gerektirdiğini gösterir. Yüksek rate görünürde success rate iyi olsa bile altyapı sorunu olduğunu gösterir. Maliyet ve latency artırır. Hata sınıfına göre ayrıştırılmalıdır. Release sonrası artış client policy değişikliğini gösterebilir.

Rate Limit Hit Rate

429 oranı provider limitlerine ne kadar yaklaşıldığını gösterir. Günün belirli saatlerinde artış capacity planning'e yardımcı olur. User veya feature bazında hangi trafik kaynak oluyor incelenebilir. Client-side limiter tuning yapılabilir. Limit aşımının RPM mi TPM mi olduğu ayrıştırılmalıdır.

Circuit Breaker Activation Rate

Breaker'ın ne sıklıkla open olduğu provider reliability hakkında güçlü sinyal sağlar. Çok sık aktivasyon threshold'un aşırı hassas olduğunu da gösterebilir. Open duration ayrıca izlenmelidir. Fallback load ile birlikte değerlendirilmelidir. Incident timeline breaker state değişimlerini içermelidir.

Fallback Rate

Fallback sistemin ana path yerine alternatif path'i ne kadar kullandığını gösterir. Yüksek oran ana provider veya modelde kalite problemi olabilir. Fallback model cost ve latency ayrıca izlenmelidir. Kullanıcı quality metric farkı varsa raporlanmalıdır. Uzun süre yüksek fallback normalleştirilmemelidir.

Token Kullanımı

Token kullanımı traffic hacminden daha anlamlı AI cost sinyali olabilir. Input context büyümesi fark edilebilir. Retry tokenları ayrı hesaplanabilir. Output limit değişikliği maliyete yansır. Feature bazlı token budget uygulanabilir.

Request Başına Maliyet

Logical request başına gerçek maliyet provider fiyatı ve token kullanımından hesaplanabilir. Retry ve fallback ek çağrıları dahil edilmelidir. Aynı feature'ın zaman içindeki maliyet trendi görülebilir. Daha pahalı model gerçekten kalite artışı sağlıyor mu değerlendirilebilir. Budget alert bu metriğe bağlanabilir.

Alerting ve Incident Management

Monitoring veri toplar, alerting ise aksiyon gerektiren durumu erken bildirir. Her küçük latency değişimi alarm üretirse ekip alarm yorgunluğu yaşar. Error rate, provider outage ve budget gibi kullanıcı etkisi yüksek sinyaller önceliklendirilmelidir. Runbook incident sırasında hangi adımların uygulanacağını standartlaştırır. Circuit breaker ve feature flag gibi mekanizmalar operasyon ekibine hızlı kontrol sağlar.

Hangi Durumlarda Alarm Üretilmeli?

Alarm kullanıcı etkisi veya finansal risk anlamlı hale geldiğinde üretilmelidir. Validated success rate keskin düşüşü güçlü sinyaldir. P95 latency SLA üzerinde belirli süre kalabilir. 429 ani artışı kapasite problemi gösterebilir. Alert koşulları minimum trafik hacmiyle birlikte değerlendirilmelidir.

Error Rate Threshold

Tek sabit yüzde bütün servisler için uygun değildir. Baseline ve normal variance incelenmelidir. Warning ve critical seviyeler ayrılabilir. Error type bazlı farklı threshold uygulanabilir. Authentication error'da düşük oran bile deployment problemi gösterebilir.

Latency Threshold

Latency alarmı percentile üzerinden tasarlanmalıdır. P95 veya P99 belirli süre SLA üzerinde kalırsa alert üretilebilir. Tek outlier alarm oluşturmamalıdır. Queue wait ve provider latency ayrı metriğe sahip olabilir. Routing otomatik olarak daha hızlı provider'a geçebilir.

Provider Outage Alarmı

5xx ve connection failure artışı provider outage gösterebilir. Circuit breaker state alarm sinyaline dahil edilebilir. Multi-region veya multi-provider karşılaştırması root cause'a yardımcı olur. Status page entegrasyonu ek bilgi sağlayabilir. Otomatik fallback çalışsa bile operasyon ekibi outage'dan haberdar olmalıdır.

Kota ve Bütçe Alarmı

Monthly budget'ın yüzde 80 veya 90 seviyesine yaklaşması önceden uyarı verebilir. Günlük token tüketimindeki ani artış kötüye kullanım veya retry storm gösterebilir. Kullanıcı bazlı harcama limiti ek kontrol sağlar. Hard quota'ya çarpmadan önce trafik policy değiştirilebilir. Finance ve platform ekibi aynı dashboard'u kullanabilir.

Runbook Oluşturma

Runbook her alarm için ilk kontrol adımlarını açıklar. Hangi dashboard'a bakılacağı ve hangi feature flag'in kullanılacağı yazılmalıdır. Provider outage durumunda fallback veya queue adımı tanımlanır. Rollback ve iletişim sorumlusu belli olmalıdır. Runbook düzenli game day testleriyle doğrulanmalıdır.

AI API Maliyetlerini Hata Yönetimiyle Birlikte Kontrol Etmek

Hata yönetimi kötü tasarlandığında maliyet görünmeden büyür. Timeout ve retry aynı prompt'u defalarca gönderebilir. Uzun context ve yüksek output limiti her attempt'in maliyetini artırır. Cache ve küçük model fallback'i maliyet kontrolüne katkı sağlar. Güvenilirlik ve maliyet bu nedenle ayrı mimari başlıklar değil aynı sistem tasarımının parçalarıdır.

Başarısız Retry'ların Maliyeti

Her retry ücretsiz değildir. Request model tarafından kısmen işlendiğinde token maliyeti oluşabilir. Timeout istemci tarafında olsa bile provider generation yapmaya devam etmiş olabilir. Logical request başına attempt count ve cost izlenmelidir. Retry policy cost budget ile sınırlandırılabilir.

Token Budget Oluşturmak

Her feature için maximum input ve output token sınırı belirlenebilir. Kullanıcı role veya plan bazında farklı budget uygulanabilir. Conversation history limit altında tutulur. Background job toplam token budget'a ulaştığında durdurulabilir. Bu politika hem maliyet hem rate-limit davranışını iyileştirir.

Prompt Boyutunu Kontrol Etmek

Gereksiz system prompt ve uzun context doğrudan maliyet oluşturur. RAG yalnızca ilgili chunk'ları göndermelidir. Conversation summary tekrar eden geçmişi kısaltabilir. Tokenization öncesi yaklaşık length kontrolü yapılabilir. Prompt optimization kalite metriğiyle birlikte test edilmelidir.

Daha Ucuz Model Fallback'i

Basit istekler büyük model yerine daha küçük modele gönderilebilir. Provider yoğunluğunda küçük model availability açısından da daha iyi olabilir. Ancak fallback output kalite threshold'u sağlamalıdır. Task benchmark bu kararı desteklemelidir. Cost saving kullanıcı şikayetini artırıyorsa gerçek tasarruf olmayabilir.

Cache ile Gereksiz API Çağrılarını Azaltmak

Deterministic veya tekrarlayan sorular cache için uygundur. Semantic cache benzer prompt'ları eşleştirebilir ancak yanlış eşleşme riski taşır. Cache freshness ve user scope dikkatle tasarlanmalıdır. Model version değişiminde cache invalidation gerekir. Cache hit rate ve avoided cost raporlanabilir.

Kullanıcı Bazlı Harcama Limitleri

Tek bir kullanıcı script hatasıyla bütün kotayı tüketebilir. User veya API client bazında günlük token sınırı uygulanabilir. Limit aşıldığında request queue veya daha küçük modele yönlendirilebilir. Admin override kontrollü olmalıdır. Harcama dashboard departman bazında görünürlük sağlayabilir.

AI API Entegrasyonlarını Test Etmek

AI entegrasyonu yalnızca happy path test edilirse production hatalarında beklenmeyen davranış gösterir. Unit test error classifier ve retry policy'yi doğrular. Integration test gerçek veya staging provider ile contract uyumunu kontrol eder. 429, timeout, 503 ve invalid response senaryoları bilinçli simüle edilmelidir. Chaos yaklaşımı sistemin dependency failure altında gerçekten graceful davranıp davranmadığını gösterir.

Unit Test

Retryable ve non-retryable error mapping unit test ile doğrulanabilir. Backoff calculation deterministic random seed ile test edilebilir. Schema validation failure senaryoları oluşturulur. Circuit breaker state transition izole test edilir. Network çağrısı mock edilerek hızlı test suite elde edilir.

Integration Test

Gerçek SDK ve HTTP stack staging ortamında denenmelidir. Authentication, timeout ve streaming davranışı doğrulanır. Provider schema değişikliği contract test ile yakalanabilir. Maliyet nedeniyle test prompt'ları küçük tutulabilir. Production credential kullanılmamalıdır.

Mock AI Provider Kullanımı

Mock server belirli status code ve gecikmeleri kontrollü üretir. CI ortamında gerçek provider'a bağımlılığı azaltır. Streaming chunk sequence simüle edilebilir. Invalid JSON ve disconnect senaryoları kolayca üretilebilir. Mock response gerçek provider formatına yakın tutulmalıdır.

429 Hatasını Simüle Etmek

Mock provider birkaç request sonrası 429 döndürebilir. Retry-After header farklı değerlerle test edilir. Client-side limiter'ın yeni request'i bekletip bekletmediği kontrol edilir. Retry count ve final fallback doğrulanır. Testte sonsuz retry olmadığından emin olunmalıdır.

Timeout Simülasyonu

Mock server bağlantıyı kabul edip response'u geciktirebilir. Connection ve read timeout ayrı test edilir. Timeout sonrası idempotency davranışı kontrol edilir. Retry toplam workflow deadline'ı aşmamalıdır. Streaming inter-chunk timeout ayrıca simüle edilmelidir.

500/503 Provider Hatasını Simüle Etmek

Belirli hata oranında 500 veya 503 döndüren mock kullanılabilir. Backoff ve jitter behavior log üzerinden doğrulanır. Circuit threshold'a ulaşınca open olmalıdır. Fallback provider devreye girmelidir. Recovery sonrası half-open state test edilir.

Circuit Breaker Testi

Arka arkaya başarısız çağrılar gönderilir. Failure threshold sonrası provider'a gerçek call yapılmadığı doğrulanır. Cooldown tamamlanınca half-open test request kontrol edilir. Başarılı probe circuit'i closed duruma döndürmelidir. Metric ve log event'leri de test edilebilir.

Fallback Senaryosu Testi

Ana provider intentionally unavailable yapılır. Alternatif provider'ın doğru request formatı aldığı kontrol edilir. Response normalized schema'ya dönmelidir. Fallback model kalite testinden geçmelidir. Kullanıcıya duplicate veya çelişkili response gönderilmemelidir.

Chaos Engineering Yaklaşımı

Staging veya kontrollü production ortamında dependency latency ve failure enjekte edilebilir. Amaç sistemi bozmak değil failure behavior'ı doğrulamaktır. DNS failure, provider timeout ve queue backlog senaryoları seçilebilir. Runbook ve alert response birlikte test edilir. Deney blast radius küçük tutulmalıdır.

Production-Ready AI API Mimari Akışı

Dayanıklı mimari request'in provider'a doğrudan geçmesine izin vermez. Önce validation ve authentication yapılır. AI client abstraction timeout, retry ve circuit breaker policy uygular. Provider başarısızsa uygun fallback seçilir. Response application schema ile doğrulanıp logging ve metrics sonrasında kullanıcıya kontrollü biçimde sunulur.

Request Validation

Input type ve zorunlu alanlar provider çağrısından önce kontrol edilir. Prompt length ve allowed parameter sınırları uygulanır. Zararlı veya beklenmeyen payload filtrelenebilir. Validation error non-retryable olur. Kullanıcıya anlaşılır hata döndürülür.

Authentication ve Rate Limiting

Kullanıcının kendi uygulama kimliği doğrulanır. AI provider key kullanıcıya gösterilmez. Tenant quota ve request rate kontrol edilir. Provider global rate limit ayrıca göz önünde tutulur. Abuse ve runaway script erken durdurulur.

AI Client / Provider Abstraction

Business service ortak AI interface çağırır. Provider adapter SDK ayrıntısını yönetir. Error normalization bu katmanda yapılabilir. Request ve response modeli standardize edilir. Provider değişimi uygulamanın geri kalanını minimum etkiler.

Timeout

Connection ve request timeout açık biçimde tanımlanır. Workflow deadline kalan retry süresini sınırlar. Streaming TTFT ve chunk timeout ayrı olabilir. Timeout metriği kaydedilir. Değerler gerçek percentile latency'ye göre güncellenir.

Retry + Exponential Backoff + Jitter

Yalnızca retryable error sınıfları tekrar denenir. Backoff her attempt'te artar. Jitter retry synchronization'ı azaltır. Maximum retry ve retry budget uygulanır. Retry sonunda fallback veya controlled failure devreye girer.

Circuit Breaker

Provider genel health problemi yaşadığında yeni request'ler hızlı biçimde durdurulur. Open state kullanıcı latency'sini azaltır. Fallback trafik alır. Recovery half-open probe ile doğrulanır. Circuit state monitoring dashboard'a eklenir.

Model / Provider Fallback

Fallback policy use case bazında belirlenir. Küçük model, alternatif provider veya cache seçilebilir. Veri gizliliği constraint uygulanır. Fallback response aynı business schema'dan geçer. Fallback rate metric olarak kaydedilir.

Response Validation

HTTP success sonrası JSON ve type validation yapılır. Business rule kontrol edilir. Hatalı output repair veya limited retry'a gidebilir. Critical field eksikse kullanıcıya yanlış sonuç verilmez. Validated success metriği bu katmandan üretilir.

Logging ve Metrics

Request ID, provider, model ve latency kaydedilir. Token, retry ve error type metriğe dönüştürülür. Prompt mümkün olduğunca loglanmaz. Trace correlation bütün servisleri bağlar. Incident ve maliyet analizi aynı observability verisini kullanır.

Kullanıcıya Kontrollü Response

Provider error detail doğrudan kullanıcıya aktarılmaz. Kullanıcıya tekrar deneme veya alternatif işlem sunulur. Partial veya fallback response uygun biçimde işaretlenir. Support için request ID gösterilebilir. Ana uygulama AI servisi geçici olarak çalışmasa bile mümkün olduğunca kullanılabilir kalır.

Production'a Çıkmadan Önce Kontrol Listesi

Production öncesi kontrol yalnızca API key'in çalışıp çalışmadığına bakmamalıdır. Security, retry, timeout, rate limit, idempotency ve fallback senaryoları doğrulanmalıdır. Monitoring dashboard ve alert'ler deployment öncesinde hazır olmalıdır. Load ve failure testleri gerçek trafik profilini taklit etmelidir. Maliyet kontrolü de release kriterinin parçası olmalıdır.

Güvenlik Kontrolleri

API key source code ve frontend içinde bulunmamalıdır. Secret manager ve least privilege uygulanmalıdır. Prompt ve response log politikası kontrol edilmelidir. TLS ve outbound network policy doğrulanmalıdır. Service account access review yapılmalıdır.

Retry Politikası Kontrolleri

Retryable error listesi açık olmalıdır. SDK ve application double retry kontrol edilmelidir. Maximum attempt ve elapsed time sınırı bulunmalıdır. Jitter test edilmelidir. Retry cost dashboard görünür olmalıdır.

Timeout Kontrolleri

Connection ve response timeout ayrı tanımlanmalıdır. Workflow deadline bulunmalıdır. Streaming timeout test edilmelidir. Timeout sonrası duplicate side effect riski değerlendirilmelidir. Değerler load test sonucuna göre ayarlanmalıdır.

Rate Limit Kontrolleri

Provider RPM ve TPM limitleri bilinmelidir. Client-side limiter uygulanmalıdır. Queue veya concurrency semaphore test edilmelidir. Retry-After parsing doğrulanmalıdır. 429 alert ve dashboard hazır olmalıdır.

Idempotency Kontrolleri

Side-effect işlemlerde key üretilmelidir. Retry aynı key'i korumalıdır. Database unique constraint gerektiğinde uygulanmalıdır. Webhook receiver duplicate event'e dayanıklı olmalıdır. Idempotency storage retention belirlenmelidir.

Fallback Kontrolleri

Ana provider kapatılarak gerçek fallback testi yapılmalıdır. Alternatif model response schema'sı doğrulanmalıdır. Privacy policy provider routing'i sınırlamalıdır. Static veya cache fallback UI tarafından doğru gösterilmelidir. Fallback loop oluşmamalıdır.

Logging ve Monitoring Kontrolleri

Request ID bütün servislerde görünmelidir. Token ve cost metriği kaydedilmelidir. Prompt leak olmadığından emin olunmalıdır. Alert test amaçlı tetiklenmelidir. Dashboard model ve provider filtrelerini desteklemelidir.

Maliyet Kontrolleri

Request başına yaklaşık ve gerçek cost hesaplanmalıdır. Kullanıcı ve feature budget belirlenmelidir. Retry cost ayrıca izlenmelidir. Expensive model kullanımı sınırlandırılabilir. Budget alarm production öncesinde test edilmelidir.

Load Test ve Failure Testleri

Peak concurrency gerçekçi senaryoyla test edilmelidir. 429 ve provider timeout birlikte simüle edilmelidir. Circuit breaker activation gözlemlenmelidir. Queue backlog recovery ölçülmelidir. User-facing degradation behavior product ekibiyle birlikte doğrulanmalıdır.

Sık Sorulan Sorular

API Üzerinden AI Servis Tüketimi ve Hata Yönetimi konusunda en sık sorulan sorular retry sayısı, timeout değeri, 429 davranışı ve provider fallback etrafında toplanır. Tek bir sabit cevap bütün uygulamalara uymaz. Kullanıcı beklentisi, provider SLA, model latency ve request'in side effect üretip üretmediği kararı değiştirir. En sağlıklı yöntem hata türünü sınıflandırıp her sınıf için açık policy belirlemektir. Aşağıdaki cevaplar production ortamları için güçlü başlangıç noktaları sunar.

AI API isteği başarısız olduğunda kaç kez retry yapılmalı?

Genel olarak interaktif isteklerde az sayıda retry tercih edilmelidir. İki veya üç attempt birçok sistem için başlangıç olabilir ancak bu evrensel kural değildir. Total elapsed time ve workflow timeout daha önemli olabilir. Background job daha uzun retry policy kullanabilir. Permanent error'larda hiç retry yapılmamalıdır.

429 Too Many Requests hatası nasıl çözülür?

Önce 429'un RPM, TPM, concurrency veya hard quota kaynaklı olup olmadığı anlaşılmalıdır. Retry-After varsa uygulanmalıdır. Exponential backoff ve jitter kullanılmalıdır. Client-side rate limiter ve queue burst'leri kontrol eder. Hard quota bitmişse retry yerine budget veya fallback aksiyonu gerekir.

Her 500 hatasında retry yapılmalı mı?

Hayır. 500 çoğu zaman transient olabilir ama sürekli aynı request'te tekrar ediyorsa farklı problem bulunabilir. Maximum retry sayısı uygulanmalıdır. Error rate yükseldiğinde circuit breaker açılabilir. Invalid provider response veya deterministic bug varsa retry faydasız olabilir. Provider error body ve trace incelenmelidir.

Exponential backoff ve jitter arasındaki fark nedir?

Exponential backoff her retry arasındaki bekleme süresini kademeli artırır. Jitter bu bekleme süresine rastgelelik ekler. Backoff provider'a toparlanma süresi verir. Jitter çok sayıda client'ın aynı anda yeniden denemesini önler. İkisi genellikle birlikte kullanılmalıdır.

AI API için ideal timeout kaç saniyedir?

Tek bir ideal saniye değeri yoktur. Kısa classification ile uzun generation aynı timeout'u kullanmamalıdır. P95 ve P99 gerçek latency ölçülmelidir. Connection timeout response timeout'tan daha kısa olabilir. Kullanıcı workflow'u için toplam deadline ayrıca belirlenmelidir.

Circuit breaker ne zaman kullanılmalı?

Harici AI provider sistemin önemli bağımlılığıysa circuit breaker faydalıdır. Sürekli 5xx veya connection failure durumunda yeni request'i hızlı durdurur. Retry storm ve connection exhaustion riskini azaltır. Fallback veya graceful degradation ile birlikte kullanılır. Çok düşük trafikli basit prototipte gerekli olmayabilir.

Bir AI servisi çökerse otomatik olarak başka modele geçilebilir mi?

Evet, model veya provider fallback uygulanabilir. Ancak response format ve model kalitesi önceden test edilmelidir. Farklı provider'a veri göndermek privacy koşullarını değiştirebilir. Routing policy yalnızca approved seçeneklere geçmelidir. Fallback sonucu monitoring altında ayrıca izlenmelidir.

OpenAI, Gemini ve Anthropic aynı fallback yapısında kullanılabilir mi?

Tek bir abstraction layer üzerinden farklı provider adapter'ları kullanmak mümkündür. Ancak model parametreleri, tool calling ve structured output behavior aynı değildir. Ortak request ve normalized response modeli gerekir. Provider-specific özellikler capability flag ile yönetilebilir. Her fallback yolu gerçek integration ve quality testlerinden geçirilmelidir.

AI API maliyetleri nasıl kontrol edilir?

Input ve output token kullanımını request bazında izlemek gerekir. Retry ve fallback attempt'leri cost hesabına dahil edilmelidir. Prompt ve conversation boyutu sınırlandırılabilir. Cache ve daha küçük model routing kullanılabilir. User veya tenant bazlı budget uygulanabilir.

Streaming sırasında bağlantı koparsa ne yapılmalı?

Partial response ayrı state olarak tutulmalıdır. Kullanıcıya yanıtın tamamlanamadığı açıkça gösterilebilir. Resume destekleniyorsa continuation kullanılabilir. Aksi durumda kontrollü yeni generation başlatılır. Side effect içeren stream workflow'larında idempotency ayrıca korunmalıdır.

HTTP 200 dönen hatalı AI cevabı nasıl yönetilir?

HTTP 200 yalnızca transport seviyesinde başarıdır. Response schema ve business validation uygulanmalıdır. Geçersiz JSON veya eksik critical field application error sayılmalıdır. Limited repair veya retry uygulanabilir. Başarısız sonuç kullanıcıya doğru veri gibi gösterilmemelidir.

API key güvenli biçimde nerede saklanmalı?

Production credential secret manager veya platformun güvenli secret storage sisteminde tutulmalıdır. Frontend içinde saklanmamalıdır. Repository'ye commit edilmemelidir. Rotation ve access control uygulanmalıdır. Log redaction credential sızıntısını engellemelidir.

Production ortamında hangi AI API metrikleri izlenmeli?

Validated success rate ve error rate temel metric'lerdir. P50, P95, P99 latency ve TTFT izlenmelidir. Retry, 429, circuit breaker ve fallback oranı güvenilirlik sinyali verir. Token ve request başına maliyet finansal görünürlük sağlar. Provider ve model bazında segmentasyon yapılmalıdır.

API üzerinden yapay zeka (AI) servisleri nasıl güvenli ve verimli şekilde tüketilir?

AI servisleri mümkün olduğunca backend veya kontrollü API gateway üzerinden tüketilmelidir. API key frontend'e verilmemeli, secret manager ve least privilege yaklaşımı kullanılmalıdır. Request validation, timeout, rate limit ve response schema kontrolü provider çağrısının çevresinde ortak client katmanına yerleştirilmelidir. Her logical request request ID, token usage ve latency gibi metadata ile izlenmelidir. Güvenli ve verimli tüketim yalnızca API çağrısının çalışması değil, maliyet ve hata davranışının production boyunca kontrol edilebilmesi anlamına gelir.

AI API entegrasyonlarında timeout, rate limit ve bağlantı hataları nasıl yönetilir?

Önce hata transient veya permanent olarak sınıflandırılmalıdır. 429 için Retry-After, client-side rate limiting ve exponential backoff kullanılabilir. Network reset ve 503 gibi geçici hatalar sınırlı retry ile tekrar denenebilir. Connection, response ve workflow timeout değerleri ayrı belirlenmelidir. Uzun süre devam eden provider sorunlarında circuit breaker, fallback veya queue yaklaşımı devreye girmelidir.

Yapay zeka API’lerinde retry, exponential backoff ve circuit breaker mekanizmaları nasıl uygulanır?

Retry yalnızca tekrar denenmesi anlamlı hata sınıflarına uygulanmalıdır. Her denemede bekleme süresi exponential backoff ile artırılmalı ve jitter eklenmelidir. Maksimum attempt, total elapsed time ve retry budget sınırları bulunmalıdır. Circuit breaker provider genel olarak başarısız olduğunda yeni istekleri geçici olarak durdurur. Bu mekanizmalar birlikte kullanıldığında tek request seviyesindeki geçici hatalar ile sistem genelindeki kesintiler ayrı şekilde yönetilebilir.

AI servislerinden dönen hatalı, eksik veya beklenmeyen yanıtlar uygulama tarafında nasıl kontrol edilmelidir?

AI response'u HTTP 200 olsa bile doğrudan güvenilir kabul edilmemelidir. JSON Schema ve type validation uygulanmalıdır. Zorunlu business field'lar ayrıca kontrol edilmelidir. Validation başarısızsa sınırlı self-repair, retry veya fallback uygulanabilir. Kritik işlemlerde insan incelemesi veya deterministic backend rule kullanılmalıdır.

AI API entegrasyonu ve hata yönetimi konusunda yakınımda danışmanlık veya eğitim nerede bulabilirim?

Yapay zeka API entegrasyonu ve yazılım danışmanlığı yakınımda şeklinde araştırma yaparken yalnızca API çağrısını kuran değil retry, timeout, observability, maliyet ve güvenlik konularını birlikte ele alan yaklaşım tercih edilmelidir. Diyarbakır Yazılım Topluluğu hakkında bilgi almak için https://www.diyarbakiryazilim.com.tr/about adresini inceleyebilirsiniz. Güncel proje ve teknik çalışma örnekleri için https://www.diyarbakiryazilim.com.tr/projects sayfası kullanılabilir. Veri panelleri ve yazılım entegrasyonlarıyla ilgili farklı bir teknik çalışma için https://www.diyarbakiryazilim.com.tr/posts/acik-kaynak-araclarla-is-zekasi-bi-panelleri-gelistirmek içeriği de incelenebilir. Kurumsal AI API entegrasyonu ve hata yönetimi hizmeti değerlendirirken production testleri, runbook, dashboard ve gerçek failure senaryolarının çalışma kapsamına dahil edilmesi önemli bir seçim kriteridir.

Sonuç: Dayanıklı ve Ölçeklenebilir AI API Entegrasyonu Nasıl Tasarlanır?

API Üzerinden AI Servis Tüketimi ve Hata Yönetimi, basit bir try-catch bloğundan çok daha geniş bir production disiplinidir. Güvenilir sistem önce hatayı doğru sınıflandırır, sonra yalnızca gerekli durumda retry yapar ve provider sorunu büyüdüğünde circuit breaker ile trafiği sınırlar. Fallback, queue ve graceful degradation kullanıcı deneyimini provider kesintilerinden korur. Structured response validation ve idempotency AI'ya özgü hataların business sürecine zarar vermesini engeller. Observability ve maliyet takibi ise bütün bu mekanizmaların gerçek production ortamında beklediğiniz gibi çalışıp çalışmadığını görünür hale getirir.

Retry Yerine Doğru Hata Sınıflandırmasına Öncelik Verin

Her hataya retry uygulamak dayanıklılık değil kontrolsüz trafik oluşturur. Invalid request hızlı fail etmelidir. Transient network veya provider hatası backoff ile tekrar denenebilir. Hard quota ve authentication problemleri farklı aksiyon gerektirir. Merkezi error classifier bütün sistemin aynı davranışı göstermesini sağlar.

Tek Bir AI Provider'a Bağımlılığı Azaltın

Uygulama mantığını provider SDK'sına doğrudan bağlamamak uzun vadede önemli esneklik sağlar. Ortak AI client ve normalized response modeli kullanılabilir. Fallback provider kalite ve privacy açısından önceden test edilmelidir. Her uygulamanın mutlaka çok provider kullanması gerekmez ancak geçiş maliyeti düşük tutulmalıdır. Kritik servislerde bu esneklik business continuity açısından ciddi değer sağlar.

Observability'yi İlk Günden Kurun

İlk production gününden itibaren request ID, latency, token, retry ve error type kaydedilmelidir. Sonradan log eklemek geçmiş incident verisini geri getirmez. Dashboard provider ve model bazında filtrelenebilmelidir. Alert ve runbook birlikte hazırlanmalıdır. Kullanıcı şikayeti geldiğinde hangi request'in neden başarısız olduğunu dakikalar içinde görebilmek operasyon kalitesini doğrudan değiştirir.

Hata Yönetimini Maliyet ve Kullanıcı Deneyimiyle Birlikte Tasarlayın

Teknik olarak başarılı retry kullanıcıyı otuz saniye bekletiyorsa iyi deneyim olmayabilir. Fallback sonucu maliyeti üç kat artırıyorsa finansal olarak sürdürülebilir olmayabilir. Bu nedenle success rate, latency ve cost aynı karar panelinde değerlendirilmelidir. AI API entegrasyonunun hedefi yalnızca mümkün olan her durumda yanıt üretmek değil, kabul edilebilir hız, kalite ve maliyetle güvenilir hizmet sunmaktır. Yapay zeka entegrasyonu, yazılım projeleri ve teknik topluluk çalışmaları için https://www.diyarbakiryazilim.com.tr üzerinden Diyarbakır Yazılım Topluluğu ile bağlantı kurabilirsiniz.