Canlı Ortam AI API Hataları

AI özelliğiniz gece saat 2'de bozulduğunda, hata mesajları nadiren tüm hikayeyi anlatır. Bir yıl boyunca OpenAI ve Anthropic entegrasyonlarını yönettim. Hataları, hata ayıklama (debugging) açısından ne anlama geldiklerine göre gruplandırmayı öğrendim.

Hız Sınırlarını Yönetmek

OpenAI 429 hatalarının farklı nedenleri vardır. Nasıl tepki vereceğinizi bilmek için hata kodunu kontrol etmelisiniz.

  • Dakika başına istek (RPM) sınırları saniyeler içinde düzelir.
  • Dakika başına token (TPM) sınırları 60 saniye içinde düzelir.
  • Aylık kota tükenmesi, kredi ekleyene veya faturalandırma döngüsü sıfırlanana kadar bozuk kalmaya devam eder.

Kota sorunları için exponential backoff kullanmayın. Bu sadece vaktinizi boşa harcar.

Anthropic 529 hataları, sağlayıcının aşırı yüklendiği anlamına gelir. Bunu bir 503 hatası gibi değerlendirin. Sorun onların tarafındadır. Geri çekilin ve ekibinizi uyarın.

400 Hatalarını Yönetmek

Bu hatalar genellikle sizin hatanızdır. Şu üç kalıba dikkat edin:

  • Model sürüm uyumsuzlukları. Bir yerde bir ismi güncellediniz ancak yeniden deneme yöneticinizde (retry handler) güncellemediniz.
  • Bağlam penceresi (context window) taşması. Konuşma geçmişi çok büyüdü. Bu durum genellikle hatalı kırpma (truncation) mantığı nedeniyle gerçekleşir.
  • Şema doğrulama hataları. JSON yapınız desteklenmeyen türlere veya özyinelemeli (recursive) referanslara sahip.

Bunları düzeltmek için, 400 hataları için tüm istek içeriğini (request payload) günlüğe kaydedin. Önce kullanıcı verilerini maskeleyin. Yanıt gövdesi (response body), tam olarak hangi alanın hata verdiğini size söyleyecektir.

Zaman Aşımı Hatalarını Yönetmek

Zaman aşımlarını takip etmek zordur çünkü sağlayıcı bir sorun görmez.

  • Bağlantı zaman aşımı (Connect timeout). El sıkışma (handshake) başarısız oldu. Bu, sağlayıcıdaki kesintiler (brownout) veya DNS sorunları sırasında gerçekleşir. Giden ağınızı kontrol edin.
  • Okuma zaman aşımı (Read timeout). Model başladı ancak tamamlanmadı. Uygulamanız kısmi akış çıktılarını (partial streaming outputs) yönetebilmelidir.
  • Ağ geçidi zaman aşımı (Gateway timeout - 504). Proxy'niz önce zaman aşımına uğradı. İstek sağlayıcı tarafında hâlâ çalışıyor olabilir. Yeniden denemeden önce tekilleştirme (deduplication) kullanın.

Hata ayıklamak için, bağlantı zaman aşımınızı okuma zaman aşımından ayırın. Gecikmenin nerede olduğunu bulmak için ilk token süresini (time-to-first-token) günlüğe kaydedin.

Sağlayıcı Sorunlarını Yönetmek

  • 500 hatası genellikle iki saniye sonra yapılan tek bir yeniden deneme ile çözülür.
  • 503 hatası, hizmetin performansının düştüğü anlamına gelir. Eğer sağlayıcının durum sayfası bir olay (incident) gösteriyorsa, bir devre kesici (circuit breaker) kullanın.
  • Hangi model sürümünün hata verdiğini her zaman kaydedin. Farklı modellerin farklı güvenilirlik seviyeleri vardır.

Günlüklerden Slack'e atlamayı bırakın. Önce sağlayıcının durum sayfasını kontrol edin. Bu sizi 20 dakikalık panikten kurtarır.

Kaynak: https://dev.to/void_stitch/production-ai-api-failures-by-category-what-429s-529s-and-timeouts-are-actually-telling-you-5bo1

İsteğe bağlı öğrenme topluluğu: https://t.me/GyaanSetuAi